SIC-DJ — Real-Time Audio Intelligence

01 · Overview 01 · 概覽

What is SIC-DJ?

什麼是 SIC-DJ？

SIC-DJ continuously listens to your DJ mixer output, classifies every audio moment into one of 5 structured token types, and logs it as a cryptographically verified event. The result: a queryable, replayable fingerprint of your unique musical style.

SIC-DJ 持續監聽 DJ 混音器輸出，將每個音訊時刻分類為 5 種結構化 Token，並以加密驗證的方式記錄。結果是一份可查詢、可重放的個人音樂風格指紋。

USB Audio USB 音訊

→

Ring Buffer 環形緩衝

→

Tokenizer (7 mod) 分詞器（7模組）

→

Event Bus (ZMQ) 事件總線

→

SQLite WAL

→

WebSocket

→

Three.js Pool 視覺化池

DETERMINISTIC HASHING

確定性雜湊

Every audio event carries a SHA-256 fingerprint computed from canonical JSON. Fully reproducible, replayable, and auditable.

每個音訊事件都有 SHA-256 指紋，從標準 JSON 計算得出，完全可重現、可重放、可稽核。

SESSION-GATED

Session 管控

Events only record during active DJ sessions. End a session to compute style_weights — your musical signature normalized to 1000 milli-scale.

事件只在活躍 Session 中記錄，結束時計算 style_weights，將你的音樂風格標準化為千分比。

AUTO-CALIBRATION

自動校準

Learns your mixing environment in the first 10 seconds. Adapts energy reference level from RMS distribution. Works with any USB audio interface.

前 10 秒自動學習混音環境，從 RMS 分布自動校準能量參考值，相容任何 USB 音訊介面。

02 · Token Types 02 · Token 類型

5 Token Classes

5 種 Token 類型

Every audio moment is classified into one of five token types based on spectral character, energy level, and temporal context.

每個音訊時刻依據頻譜特性、能量水平與時間背景，被分類為五種 Token 之一。

BASS_LINE

Low frequency dominance. The rhythmic foundation that holds the floor together — dark, heavy, constant.

低頻主導。支撐整個舞池的節奏基石——暗沉、厚重、持續存在。

dark low_freq

RHYTHM_LOOP

Mid-range groove. The pulse that keeps bodies moving.

中頻律動。讓身體持續移動的脈搏。

warm · mid_freq

MELODIC_PHRASE

High freq hook. The thing you remember after.

高頻旋律。演出結束後還在腦中的那條線。

bright · high_freq

FX_SWEEP

Spectral shift detected. A timbre in transit.

頻譜位移偵測。音色正在移動中。

Δspectral > 0.15

SILENCE

Space is data too. Intentional silence, logged.

留空也是資訊。刻意的靜默，同樣被記錄。

energy < 10milli

03 · Analysis Engine 03 · 分析引擎

7 Analysis Modules

7 個分析模組

The tokenizer runs 7 parallel analysis modules, each operating at its own interval, to build a complete picture of the audio signal.

分詞器並行運行 7 個分析模組，每個都有自己的採樣間隔，共同建構完整的音訊信號圖像。

50ms

ENERGY ANALYSIS能量分析

→ energy_milli (0–1000)

Loudness envelope per channel via RMS computation.

每頻道的 RMS 能量包絡，0–1000 毫單位。

200ms

SPECTRAL CHARACTER頻譜特性

→ dark / warm / bright / sharp

FFT → 4-band energy distribution classification.

FFT 四頻帶能量分布分類。

4 sec

BPM ESTIMATIONBPM 估算

→ bpm_milli

Onset detection via scipy.signal.find_peaks on energy envelope.

透過 scipy 的 find_peaks 從能量包絡中偵測節拍。

per-token

BEAT PHASE節拍相位

→ 0–3

Relative position within the 4-beat cycle for rhythmic context.

4 拍週期中的相對位置，提供節奏脈絡。

500ms

CHANNEL ROLE頻道角色

→ playing / incoming / idle / fx_return

MIDI fader position inference to classify each channel's current role.

從 MIDI 推桿位置推斷每頻道的當前角色。

event

TRANSITION DETECTION過場偵測

→ transition_start / end

Crossfader movement tracking — catches the moment you mix in a new track.

交叉推桿動態追蹤，捕捉你混入新曲目的瞬間。

per-token

STYLE TAGS風格標籤

→ house / techno / bass / …

Semantic labels derived from the combination of spectral + energy + phase analysis.

從頻譜、能量與相位分析組合衍生的語意標籤。

04 · By the Numbers 04 · 數字說話

Production Ready

生產就緒

74/74

TESTS PASSED

測試通過

<50ms

EVENT LATENCY

事件延遲

7

ANALYSIS MODULES

分析模組

4600+

TOKENS / SESSION TEST

每 Session 測試 Token 數

10/10

event_id REPRODUCIBILITY

事件 ID 可重現率

05 · Architecture 05 · 架構

SIC-JS v1.4 Protocol

SIC-JS v1.4 協議

Every event is canonical, deterministic, and self-describing — always reproducible, always replayable.

每個事件都是標準化、確定性且自描述的——永遠可重現，永遠可重放。

// SIC-JS v1.4 Event Schema { event_id : SHA256(canonical_json)[:16], // deterministic event_type : "audio_token", source : "sic_dj", timestamp_ns : <nanosecond epoch>, session_id : <UUID v4>, prev_event_id: <causal chain pointer>, // v0.2 payload : { token_type : "bass_line" | "rhythm_loop" | "melodic_phrase" | "fx_sweep" | "silence", energy_milli : 0–1000, spectral_character: "dark" | "warm" | "bright" | "sharp", beat_phase : 0–3, origin_channel : 1–4, bpm_milli : <BPM × 1000>, spectral_vector : [sub, low, mid, high] // v0.2 } }

06 · Stack 06 · 技術棧

Built On

技術棧

BACKEND (Python 3.11+)

後端 (Python 3.11+)

▸sounddevice

▸numpy

▸scipy

▸mido · python-rtmidi

▸pyzmq

▸websockets

▸sqlite3 (WAL)

FRONTEND (React + TS)

前端 (React + TypeScript)

▸React 19

▸TypeScript 4.9

▸Three.js 0.183

▸@react-three/fiber

▸@react-three/drei

▸reconnecting-websocket

07 · Get Started 07 · 開始使用

One Command

一行指令啟動

Connect your USB audio interface, clone the repo, and run. SIC-DJ will auto-detect your audio device and calibrate in the first 10 seconds.

連接 USB 音訊介面，克隆 repo，執行。SIC-DJ 會自動偵測音訊裝置並在前 10 秒完成校準。

bash
# clone & enter# 複製並進入目錄
git clone https://github.com/[repo]/sic-dj-app
cd sic-dj-app
 
# install dependencies# 安裝依賴套件
pip install -r requirements.txt
 
# start (backend + frontend in one shot)# 一鍵啟動（前後端同時）
bash start.sh
 
# open the pool visualization# 開啟視覺化介面
open http://localhost:3000

LIST DEVICES

列出裝置

python -m backend.main --list-devices

MIDI LEARN

MIDI 學習模式

python -m backend.main --midi-learn

OPEN TO MUSIC LOVERS 歡迎熱愛音樂的你

If music is your language,
let's talk.

如果音樂是你的語言，
我們想認識你。

Write to us — we'll send you the repo link directly.
No forms, no waitlists. Just music people.

來信即可取得完整檔案連結。
不用填表，不用等待。只要你熱愛音樂。

✉ Write to Us ✉ 來信索取

08 // PROTOCOL

08 // 協議守則

The Rules

底線

Verified stable across all versions. These don't change.

跨版本驗證穩定，這些不動。

01 — Single Source of Truth 01 — 單一真相來源

One module owns canonicalization. Nothing else touches it. 標準化只有一個入口，其他模組不插手。

02 — Event IDs Are Deterministic 02 — 事件 ID 確定性計算

Given the same input, you always get the same ID. Always reproducible, always auditable. 相同輸入永遠產生相同 ID，完全可重現、可稽核。

03 — Events Are Replayable 03 — 事件可重放

Every logged event can be loaded and re-verified. The record of your performance never drifts. 每筆記錄的事件都可重新載入並驗證。你的演出記錄不會漂移。

04 — Integer-Only Time Math 04 — 時間計算只用整數

Latency is always computed with integer division. No floating-point drift in timing data. 延遲計算全程整數除法，計時數據沒有浮點誤差。

05 — Style Weights Always Sum to 1000 05 — 風格權重總和恆為 1000

Your musical fingerprint is normalized to a fixed scale — comparable across every session you ever play. 你的音樂指紋標準化為固定刻度，每場演出都可橫向比較。

05 — style_weights Sum = 1000 05 — style_weights 總和恆為 1000

Always exactly 1000. Last token type absorbs rounding. 加總恆為 1000，最後一個 token 類型吸收 rounding 誤差。