Docs: comprehensive README of all features; bump to 1.1.0
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
lucianoandClaude Opus 4.8 committed
1 parent
4604b42f8f
commit
144aaaa233
2 files changed
+163
-49
No files matched your search
@@ -2,18 +2,34 @@
|
|||||||
|
|
||||||
> di **Dj LuZa** · info@djluza.com
|
> di **Dj LuZa** · info@djluza.com
|
||||||
|
|
||||||
App desktop (Electron) per Mac che mostra **frattali e visual astratti reattivi all'audio** su uno schermo esterno. L'audio può arrivare da un **file caricato** (con **playlist** riordinabile e tasti rapidi), da un **input live** (microfono / line-in) o dall'**audio di sistema** (il tuo set DJ) tramite un device virtuale tipo BlackHole. Puoi sovrapporre **immagini** e **scritte scorrevoli**.
|
App desktop (Electron) per **Mac** che proietta su uno **schermo esterno** dei visual
|
||||||
|
**reattivi all'audio** — frattali, astratti, silhouette, VU-meter, waveform e altro —
|
||||||
|
con playlist audio/video, scene a tempo, overlay grafici, testo scorrevole e
|
||||||
|
**registrazione MP4**. Pensata per DJ e VJ.
|
||||||
|
|
||||||
Include un **motore di effetti parametrico**: 16 famiglie di shader × palette di colori × varianti di stile generano **oltre 1500 preset**, con una **sequenza di effetti** (playlist) ad auto-cambio a tempo o sul beat.
|
L'audio può arrivare da **file**, da un **input live** (mic / line-in) o
|
||||||
|
dall'**audio di sistema** (il tuo set) tramite un device virtuale tipo BlackHole.
|
||||||
|
|
||||||
## Due finestre
|
---
|
||||||
|
|
||||||
All'avvio si aprono **due finestre**:
|
## Indice
|
||||||
|
|
||||||
- **Controlli** — il pannello con tutte le funzioni (sorgente audio, scene, slider, immagini, testo, scelta monitor). Sta sul tuo schermo principale.
|
- [Avvio](#avvio)
|
||||||
- **Output** — solo la visualizzazione, senza interfaccia. Va automaticamente a schermo intero sul monitor esterno se presente.
|
- [Architettura a due finestre](#architettura-a-due-finestre)
|
||||||
|
- [Le schede del pannello](#le-schede-del-pannello)
|
||||||
|
- [🎵 Audio](#-audio)
|
||||||
|
- [🌀 Effetti](#-effetti)
|
||||||
|
- [🎹 Pad](#-pad)
|
||||||
|
- [🖼 Immagini](#-immagini)
|
||||||
|
- [🔤 Testo](#-testo)
|
||||||
|
- [🔴 Registra](#-registra)
|
||||||
|
- [🖥 Schermo](#-schermo)
|
||||||
|
- [Scorciatoie da tastiera](#scorciatoie-da-tastiera)
|
||||||
|
- [Audio di sistema con BlackHole](#audio-di-sistema-con-blackhole)
|
||||||
|
- [Installazione del DMG](#installazione-del-dmg)
|
||||||
|
- [Sviluppo](#sviluppo)
|
||||||
|
|
||||||
Comandi e tasti agiscono sul pannello Controlli e si riflettono sull'Output. Chiudendo la finestra Controlli si chiude tutta l'app.
|
---
|
||||||
|
|
||||||
## Avvio
|
## Avvio
|
||||||
|
|
||||||
@@ -22,67 +38,165 @@ npm install # solo la prima volta
|
|||||||
npm start
|
npm start
|
||||||
```
|
```
|
||||||
|
|
||||||
## Controlli rapidi (tastiera)
|
## Architettura a due finestre
|
||||||
|
|
||||||
|
All'avvio si aprono **due finestre**:
|
||||||
|
|
||||||
|
- **Controlli** — il pannello con tutte le funzioni, sul tuo schermo principale.
|
||||||
|
- **Output** — solo la visualizzazione, senza interfaccia, a schermo intero sul
|
||||||
|
monitor esterno (se presente).
|
||||||
|
|
||||||
|
Comandi e tasti agiscono sul pannello e si riflettono in tempo reale sull'output.
|
||||||
|
Chiudendo la finestra Controlli si chiude l'app.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Le schede del pannello
|
||||||
|
|
||||||
|
### 🎵 Audio
|
||||||
|
|
||||||
|
- **Sorgenti**: riproduzione **file**, **input live** (mic/line/BlackHole) e
|
||||||
|
**scelta del device di uscita** (casse/cuffie/scheda audio).
|
||||||
|
- **Playlist audio e video**:
|
||||||
|
- Aggiungi **brani audio e video** (trascina o ➕). I video hanno l'icona 🎞 e
|
||||||
|
vengono mostrati a schermo intero **col loro audio** (che alimenta anche
|
||||||
|
spettro/waveform).
|
||||||
|
- **Riordina** col drag (⠿), **tasto rapido** per brano (⌨), **▶/⏸** pausa,
|
||||||
|
**clic sul nome** = avvia/riavvia dall'inizio, **Ripeti** per l'auto-avanzamento.
|
||||||
|
- **Durata** e **tempo rimanente** con **barra di avanzamento** per ogni brano.
|
||||||
|
- **🎬 Scene a tempo (cue)**: a ogni brano puoi associare una timeline di cue
|
||||||
|
(`@mm:ss`) che cambiano automaticamente **effetto + testo + immagine** mentre
|
||||||
|
il brano suona (es. `@00:00` intro, `@00:30` drop…).
|
||||||
|
- **💾 Salva / 📂 Carica** la playlist su file, e **persistenza automatica** tra
|
||||||
|
le sessioni.
|
||||||
|
- **Equalizzatore visual**: regola quanto **Bassi / Medi / Alti** influenzano la
|
||||||
|
grafica. Più **Reattività** (master) e **Velocità**.
|
||||||
|
- **Livelli** BASS/MID/HIGH in tempo reale.
|
||||||
|
- **Resa video in playlist**: fusione (normale/screen/overlay…), opacità e
|
||||||
|
adatta/riempie per i video riprodotti dalla lista.
|
||||||
|
|
||||||
|
### 🌀 Effetti
|
||||||
|
|
||||||
|
Motore di effetti **parametrico**: **29 famiglie** di shader × **17 palette** ×
|
||||||
|
**6 varianti** = **oltre 2900 preset**.
|
||||||
|
|
||||||
|
- **Libreria** filtrabile per famiglia e ricercabile per nome — clic per applicare.
|
||||||
|
Cambiando il **filtro famiglia** si applica subito il primo preset di quella
|
||||||
|
categoria.
|
||||||
|
- **Sequenza effetti**: metti in coda i preset preferiti (➕), riordina, assegna
|
||||||
|
tasti rapidi, e attiva **Auto-cambio** (a intervallo) o **Sul beat**, con **Shuffle**.
|
||||||
|
I tasti **1–9** lanciano i primi 9 della sequenza.
|
||||||
|
- **Effetti SVG / immagini**: scegli una sagoma dalla tendina (50+ SVG inclusi,
|
||||||
|
pubblico dominio) o carica un tuo SVG/immagine → diventa un effetto reattivo
|
||||||
|
(palette, simmetrie, warp).
|
||||||
|
|
||||||
|
**Categorie di effetti:**
|
||||||
|
|
||||||
|
| Categoria | Esempi |
|
||||||
|
|-----------|--------|
|
||||||
|
| Frattali / astratti | Julia, Mandelbrot, Plasma, Tunnel, Vortice, Caleidoscopi, Spirali… |
|
||||||
|
| Silhouette / persone | Ballerini (folla), Ballerino, Sagome (note musicali) |
|
||||||
|
| SVG / immagini | qualsiasi SVG/immagine come sorgente recolorabile |
|
||||||
|
| VU-Meter | barre di spettro, lancetta analogica, LED stereo |
|
||||||
|
| Waveform | forma d'onda del brano scorrevole + waveform radiale |
|
||||||
|
| Reattivi a banda | Bassi, Medi, Alti, Tri-Banda |
|
||||||
|
|
||||||
|
### 🎹 Pad
|
||||||
|
|
||||||
|
Un **launchpad 5×4** (20 pad): assegna un brano a ogni pad (clic o trascina),
|
||||||
|
premilo per avviarlo. Premendone un altro **ferma il corrente e parte il nuovo**.
|
||||||
|
- **Tasto rapido** per pad (⌨), **barra di avanzamento** sul pad attivo,
|
||||||
|
**Crossfade** tra pad, **persistenza** automatica delle assegnazioni.
|
||||||
|
|
||||||
|
### 🖼 Immagini
|
||||||
|
|
||||||
|
- **Video (loop VJ)**: carica un video che va in loop (muto) e si **fonde** coi
|
||||||
|
visual generati (opacità, modalità di fusione, adatta/riempie).
|
||||||
|
- **Immagini overlay**: slideshow ridimensionabile, durata, fusione, pulsazione
|
||||||
|
sul beat.
|
||||||
|
- **2 loghi** indipendenti: posizione libera (X/Y), dimensione e opacità.
|
||||||
|
|
||||||
|
### 🔤 Testo
|
||||||
|
|
||||||
|
Testo scorrevole con:
|
||||||
|
- **Carattere**, **grandezza**, **grassetto**, **colore**.
|
||||||
|
- **Direzione**: orizzontale, **verticale su**, **verticale giù**.
|
||||||
|
- **Effetti movimento**: su e giù, **onda** (per lettera), zoom/pulse, flash, rotazione.
|
||||||
|
- Posizione (basso/alto/centro) e velocità.
|
||||||
|
|
||||||
|
### 🔴 Registra
|
||||||
|
|
||||||
|
Registra l'output (**visual + overlay + testo + audio**) in **MP4**:
|
||||||
|
- Formati: **16:9**, **9:16**, **1:1**, **4:3**, **3:4**, **21:9**.
|
||||||
|
- Salvataggio in *Filmati ▸ DJ Visualizer*. Richiede **ffmpeg** (di sistema).
|
||||||
|
|
||||||
|
### 🖥 Schermo
|
||||||
|
|
||||||
|
Scegli il **monitor di output** e premi *Manda al monitor* (fullscreen affidabile
|
||||||
|
anche con più schermi). `F` per attivare/disattivare lo schermo intero.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scorciatoie da tastiera
|
||||||
|
|
||||||
| Tasto | Azione |
|
| Tasto | Azione |
|
||||||
|-------|--------|
|
|-------|--------|
|
||||||
| `1`–`9` | Applica i primi 9 effetti della sequenza |
|
| `1`–`9` | Applica i primi 9 effetti della sequenza |
|
||||||
| `F` | Schermo intero output |
|
| `F` | Schermo intero output |
|
||||||
| `O` | Aggiungi brani alla playlist |
|
| `O` | Aggiungi brani/video alla playlist |
|
||||||
| `G` | Carica immagini |
|
| `G` | Carica immagini |
|
||||||
| `T` | Mostra/nascondi testo scorrevole |
|
| `T` | Mostra/nascondi testo scorrevole |
|
||||||
| `← →` | Cambia immagine |
|
| `← →` | Cambia immagine overlay |
|
||||||
| `Spazio` | Play/pausa del brano |
|
| `Spazio` | Play/pausa del brano |
|
||||||
| tasti personalizzati | Avvio rapido di brani e effetti (assegnabili dal pannello con ⌨) |
|
| tasti personalizzati | Avvio rapido di brani, effetti e pad (assegnabili con ⌨) |
|
||||||
|
|
||||||
Puoi anche **trascinare** brani (mp3/wav) o immagini direttamente sul pannello.
|
Puoi anche **trascinare** brani, video o immagini direttamente sul pannello.
|
||||||
|
|
||||||
## Effetti
|
---
|
||||||
|
|
||||||
- **Libreria effetti**: oltre 1500 preset filtrabili per famiglia e ricercabili per nome. Clic per applicarli all'istante.
|
## Audio di sistema con BlackHole
|
||||||
- **Sequenza effetti**: aggiungi i preset preferiti (➕), riordinali col drag, assegna tasti rapidi, e attiva **Auto-cambio** (a intervallo) o **Sul beat** (cambia a ritmo), con **Shuffle**.
|
|
||||||
- **Equalizzatore visual**: regola quanto Bassi/Medi/Alti influenzano la grafica.
|
|
||||||
|
|
||||||
## Playlist audio
|
macOS non permette di catturare direttamente l'audio in uscita. Soluzione gratuita:
|
||||||
|
**BlackHole**.
|
||||||
Carica più brani, riordinali col drag della maniglia ⠿, assegna un tasto rapido a ciascuno (⌨), avvia/pausa per brano (▶/⏸) e attiva **Ripeti** per l'avanzamento automatico a fine traccia.
|
|
||||||
|
|
||||||
## Schermo esterno
|
|
||||||
|
|
||||||
Nel pannello, sezione **Schermo**: scegli il monitor (di default seleziona quello esterno) e premi **Vai** → la finestra si sposta e va a schermo intero su quel display. `F` per uscire.
|
|
||||||
|
|
||||||
## Sorgenti audio
|
|
||||||
|
|
||||||
- **File**: pulsante 📂 o trascina il file. L'audio si sente dalle casse del Mac.
|
|
||||||
- **Input live (mic / line-in)**: seleziona il device dal menu e premi *Usa input*. Utile con una scheda audio/mixer collegato all'ingresso.
|
|
||||||
- **Audio di sistema (il tuo set)**: serve un device virtuale, vedi sotto.
|
|
||||||
|
|
||||||
### Catturare l'audio di sistema con BlackHole
|
|
||||||
|
|
||||||
macOS non permette di catturare direttamente l'audio in uscita. Soluzione gratuita: **BlackHole**.
|
|
||||||
|
|
||||||
1. Installa BlackHole (2ch):
|
1. Installa BlackHole (2ch):
|
||||||
```bash
|
```bash
|
||||||
brew install blackhole-2ch
|
brew install blackhole-2ch
|
||||||
```
|
```
|
||||||
(oppure scaricalo da https://existential.audio/blackhole/)
|
(oppure da https://existential.audio/blackhole/)
|
||||||
|
2. In *Configurazione MIDI Audio* crea un **Multi-Output Device** che includa sia le
|
||||||
2. Per **sentire l'audio E inviarlo al visualizer** allo stesso tempo, crea un **Multi-Output Device** in *Audio MIDI Setup* (Configurazione MIDI Audio):
|
tue **casse/cuffie** sia **BlackHole 2ch**, e impostalo come uscita del Mac (o del
|
||||||
- `+` in basso a sinistra → **Create Multi-Output Device**
|
software DJ) — così senti l'audio **e** lo mandi al visualizer.
|
||||||
- spunta sia le tue **casse/cuffie** sia **BlackHole 2ch**
|
|
||||||
- imposta questo Multi-Output come uscita del Mac (o del software DJ)
|
|
||||||
|
|
||||||
3. In DJ Visualizer scegli **BlackHole 2ch** come input live e premi *Usa input*.
|
3. In DJ Visualizer scegli **BlackHole 2ch** come input live e premi *Usa input*.
|
||||||
|
|
||||||
> In alternativa, manda direttamente l'uscita del software DJ a BlackHole se preferisci non sentire nulla dalle casse del Mac.
|
---
|
||||||
|
|
||||||
## Personalizzare i visual
|
## Installazione del DMG
|
||||||
|
|
||||||
Le scene sono shader GLSL in `src/shaders.js` (array `SHADERS.scenes`). Ognuna riceve uniform audio: `uBass`, `uMid`, `uTreble`, `uLevel`, `uBeat`, più `uTime` e `uRes`. Aggiungere una scena = aggiungere uno shader all'array e un bottone in `index.html`.
|
Le release contengono un **DMG non notarizzato** (nessun Apple Developer Program).
|
||||||
|
Vedi **[RELEASE.md](RELEASE.md)** per i dettagli; in breve:
|
||||||
|
|
||||||
## Build di un .app/.dmg
|
1. Apri il DMG → trascina **DJ Visualizer** in **Applicazioni**.
|
||||||
|
2. Primo avvio: **clic destro ▸ Apri ▸ Apri**.
|
||||||
|
3. Se dice *«è danneggiata»*: `xattr -cr "/Applications/DJ Visualizer.app"`
|
||||||
|
(o doppio clic su `scripts/fix-security.command`).
|
||||||
|
|
||||||
```bash
|
---
|
||||||
npm run dist
|
|
||||||
```
|
## Sviluppo
|
||||||
Genera un `.dmg` in `dist/` (richiede electron-builder, già incluso).
|
|
||||||
|
- **Stack**: Electron + WebGL2 (shader GLSL) + Web Audio API. Nessun framework UI.
|
||||||
|
- **File principali**:
|
||||||
|
- `main.js` — finestre, IPC, gestione schermi, persistenza, registrazione (ffmpeg).
|
||||||
|
- `src/output.*` — finestra di visualizzazione (canvas, overlay, audio engine).
|
||||||
|
- `src/control.*` — pannello di controllo.
|
||||||
|
- `src/shaders.js` — l'uber-shader parametrico (tutte le famiglie).
|
||||||
|
- `src/effects.js` — generatore del catalogo (famiglie × palette × varianti).
|
||||||
|
- `src/visualizer.js`, `src/audio.js` — motore grafico e analisi audio.
|
||||||
|
- **Compilare il DMG**:
|
||||||
|
```bash
|
||||||
|
CSC_IDENTITY_AUTO_DISCOVERY=false npm run dist
|
||||||
|
```
|
||||||
|
Output in `dist/`.
|
||||||
|
|
||||||
|
Repo: https://github.com/luzadev/djaudiovisualizer
|
||||||
+1
-1
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "dj-visualizer",
|
"name": "dj-visualizer",
|
||||||
"version": "1.0.0",
|
"version": "1.1.0",
|
||||||
"description": "Audio-reactive fractal & abstract visualizer for external display (Mac)",
|
"description": "Audio-reactive fractal & abstract visualizer for external display (Mac)",
|
||||||
"main": "main.js",
|
"main": "main.js",
|
||||||
"author": {
|
"author": {
|
||||||
|
|||||||
Reference in new issue
Block a user