luzadev/djaudiovisualizer
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Docs: comprehensive README of all features; bump to 1.1.0

Browse Source 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
lucianoandClaude Opus 4.8 committed 2026-06-19 17:03:43 +02:00
1 parent 4604b42f8f
commit 144aaaa233
2 files changed
+163 -49
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+162 -48
View File
@@ -2,18 +2,34 @@
> 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.
- **Output** — solo la visualizzazione, senza interfaccia. Va automaticamente a schermo intero sul monitor esterno se presente.
- [Avvio](#avvio)
- [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
@@ -22,67 +38,165 @@ npm install # solo la prima volta
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 |
|-------|--------|
| `1`–`9` | Applica i primi 9 effetti della sequenza |
| `F` | Schermo intero output |
| `O` | Aggiungi brani alla playlist |
| `O` | Aggiungi brani/video alla playlist |
| `G` | Carica immagini |
| `T` | Mostra/nascondi testo scorrevole |
| `← →` | Cambia immagine |
| `← →` | Cambia immagine overlay |
| `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.
- **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.
## Audio di sistema con BlackHole
## Playlist audio
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**.
macOS non permette di catturare direttamente l'audio in uscita. Soluzione gratuita:
**BlackHole**.
1. Installa BlackHole (2ch):
```bash
brew install blackhole-2ch
```
(oppure scaricalo da https://existential.audio/blackhole/)
2. Per **sentire l'audio E inviarlo al visualizer** allo stesso tempo, crea un **Multi-Output Device** in *Audio MIDI Setup* (Configurazione MIDI Audio):
- `+` in basso a sinistra → **Create Multi-Output Device**
- spunta sia le tue **casse/cuffie** sia **BlackHole 2ch**
- imposta questo Multi-Output come uscita del Mac (o del software DJ)
(oppure da https://existential.audio/blackhole/)
2. In *Configurazione MIDI Audio* crea un **Multi-Output Device** che includa sia le
tue **casse/cuffie** sia **BlackHole 2ch**, e impostalo come uscita del Mac (o del
software DJ) — così senti l'audio **e** lo mandi al visualizer.
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
```
Genera un `.dmg` in `dist/` (richiede electron-builder, già incluso).
---
## Sviluppo
- **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
package.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "dj-visualizer",
"version": "1.0.0",
"version": "1.1.0",
"description": "Audio-reactive fractal & abstract visualizer for external display (Mac)",
"main": "main.js",
"author": {