DjProducerTool

DJProducerTools – Extended Manual (v1.0.0, EN)

Fundamentals

Quick CLI usage & global flags

Safety workflow (step by step)

1) Ensure SAFE_MODE=1, DJ_SAFE_LOCK=1, DRYRUN_FORCE=0 (default). Menu re-prompts to restore if set to 0. 2) Scan/catalog (6, 9, 10) before moving anything. Review TSVs. 3) Backups: 7/8 (rsync) and snapshot 27. Do this before quarantine/moves. 4) Apply moves only with Safe/Lock off and after manual confirmation (11, DMX send, etc.). 5) Use DJPT_OFFLINE=1 for labs when you cannot download models. Use --dry-run flags when offered.

Core (1–12)

Example safe flow: 6 → 9 → 10 (review TSV) → 11 only if Safe/Lock=0 and not DRY.

Media / Organization (13–24)

Processes / Cleanup (25–39)

Example transcode (hw accel): Menu 33 → codec auto → run ffmpeg? y → if DRYRUN_FORCE=1, prints commands only.

Duplicates / Consolidation (D submenu)

ML / Deep (40–52, 62–67)

Example TF Lab offline: DJPT_OFFLINE=1 + model clap_onnx in 65.1/65.2 (uses onnxruntime if present, else mock). Example API with token: Menu 50 → set token → curl with Authorization: Bearer <token>; OSC /djpt/ping with token arg returns “pong”.

Visuals / OSC / DMX (V submenu)

Why & Advantages


Legacy wiki summary (merged)


Option-by-option details (extended)

Core (1–12)

Media / Organization (13–24)

Processes / Cleanup (25–39)

Duplicates / Consolidation (D)

ML / Deep (40–52, 62–67)

TF Lab models & offline first

DJPT_OFFLINE=1 keeps every TF Lab command in heuristic/mock mode; the flag can be set globally (menu prompt or shell environment) before opening the menu. When you unset it (DJPT_OFFLINE=0 or skip the --offline flag) and install the optional runtimes (onnxruntime, tflite-runtime, tensorflow), the submenu 65 flows load:

music_tags now combines CLAP embeddings with MUSIC_TAG_PROMPTS, while video_tags grabs ffmpeg keyframes and runs them against CLIP prompts. Matching/anomalies/segments/loudness/mastering re-use embeddings through DJPT_SHARED_CORPUS/SHARED_CORPUS_DIR, so a single deep analysis per disk can be reused across others.

MusicBrainz online metadata

The master report (menu 65.14) also accepts --online/--query to hit MusicBrainz, appending title, artist, release date to reports/ml_master_report.tsv. It respects DJPT_OFFLINE: the request runs only when you explicitly toggle --online. This gives a reliable external reference for cross-checking local analyses.

Resilient Acoustic Recognition with ShazamIO (Integrations Menu - Option 9)

Designed to identify full tracks, vinyl rips, sample chops, and untagged audio across all three ecosystem environments:

5-Layer Resilience Architecture

  1. Heuristic Guard: Immediately skips short one-shots (<150 KB or <3.2s like isolated kicks or snares) to avoid wasting network calls.
  2. Ultra-Fast SQLite Cache: Located at ~/.DJProducerTools/shazam_cache.db with chunk hashing (first 128 KB + last 128 KB + total size). Repeated queries respond in 0.001 ms ([CACHE HIT]).
  3. Async Concurrency & Timeout Control: asyncio.Semaphore(3) and strict 8.0s timeout per file to prevent hanging sockets.
  4. Decoupled FFmpeg Audio Sanitizer: If the audio file header or container is malformed, extracts a pristine 16-bit 44.1 kHz PCM chunk on-the-fly.
  5. Autonomous Offline Heuristic Fallback: If network fails or no match is found on Shazam servers, heuristically parses artist, clean title, and mix/version from filename and directory path without raising unhandled exceptions.

Output: structured TSV report (_DJProducerTools/reports/shazam_matches.tsv) with columns: file_path, match_status, title, artist, album, genre, shazam_url.

Visuals / OSC / DMX (V)

Automation (A/68)

Safety and modes

Install / venv / deps

Outputs and logs

Practical recipes

Advanced adjustments & tuning (per section)

Performance, troubleshooting, and best practices

License