Workspace Guidelines

Repository Guidelines #

1. Workspace & Server Overview #

  • Development Environment: Running on a remote Debian 12 server (IP: 173.212.213.72, hostname: 0rk.de). The server is equipped with a high-performance multi-core CPU and significant memory, but operates WITHOUT GPU acceleration.
  • Workspace Architecture: The workspace at /home/dev/ contains multiple independent, fully realized systems rather than a single monorepo. It serves as a unified workspace for audio workstations, Music Information Retrieval (MIR) visualizers, static web hydration frameworks, and various active projects.
  • Target Guidelines Purpose: This document acts as a master map for AI agents and human developers operating inside /home/dev/ to understand the architecture, run configurations, coding standards, and testing protocols of all active sub-projects.

2. Projects & Architecture #

The workspace is organized into several distinct active domains:

/home/dev/
├── audio/
│   ├── mixbox/          <-- Unified DJ Workstation (FastAPI/NiceGUI Review Server on 55644, React)
│   ├── audioflux/       <-- Gradio MIR Educational Apps (Ports 7860, 7861, 7863)
│   ├── broadcast/       <-- Broadcast Icecast/Liquidsoap setup
│   └── nicegui/         <-- NiceGUI demo & fork
├── hugdown/             <-- Hybrid Hugo (55211) & Vite React (55220) Hydration Framework
├── py/
│   ├── flow/            <-- Langflow Chatbot Workflow Builder (Port 55577)
│   ├── groqgradio/      <-- Gradio Groq Apps (Ports 55443, 55444, 55441, 55446)
│   ├── gradiomulti/     <-- Jamjams OpenAI Chat Lab via OpenRouter (Port 55442)
│   ├── mugen/           <-- Music Video Generator (cli)
│   ├── mugen-webui/     <-- Gradio WebUI for MUGEN (rhythm-based AMV cutter)
│   ├── alab/            <-- AgentLaboratory multi-agent research setup
│   ├── soup/            <-- Knowledge-base project
│   ├── yt-dlp/          <-- Customized YouTube downloader
│   ├── xray/            <-- Python project xray tools
│   ├── img/             <-- Python image cheatsheets
│   └── gitlists/        <-- Git lists helper
├── testing/
│   └── soupz/           <-- Shared unit and automation test configurations
└── active/              <-- Dynamic Sandbox (ai-town, storymatrix, ebay-sniper, fun, etc.)

A. MixBox (/home/dev/audio/mixbox/) #

MixBox is a unified audio workstation monorepo configured as an astral-uv Python workspace. It integrates automated DJ mixing, deep audio feature analysis (MIR), audio-reactive video generation, and valence-arousal emotion detection. It is composed of five sibling packages located under the /home/dev/audio/mixbox/packages/ directory:

  1. audio-core (audio_core): The shared foundation. All other packages (except emotion) depend on it. Handles raw audio loading, format conversion (NumPy/Pydub), and feature extraction constants.
  2. dj-engine (mixbox): The primary orchestrator. Contains the mixing engine, beatgrid analyzer, user interfaces, and the review planning/websocket service.
  3. analyzer (hitscan): Music Information Retrieval (MIR) package. Extracts features (BPM, key, beat alignment, structural segments), supports source separation, and renders HTML/PDF reports.
  4. video-gen (hitvid): Visual generator package. Renders beat-synchronized visualizers and psychedelic FX based on audio analysis.
  5. emotion (valaro): Standalone valence-arousal emotion classifier using Essentia MusiCNN models in TensorFlow.

Data Flow: Raw Audio $\rightarrow$ analyzer/emotion (features, SQL database) $\rightarrow$ dj-engine (mix timelines/transitions) $\rightarrow$ video-gen (beat-reactive video) + mixed audio exports. Review Services:

  • NiceGUI Review /preview Route: An operational authoring editor (packages/dj-engine/src/mixbox/gui/main.py) utilized by operators to view/override mix configurations and preview transitions. Runs on Port 55644.
  • OpenDAW Reviewer: A custom React timeline UI cockpit (user/opendaw-test/) that connects to the dj-engine WebSocket API (/ws/timeline) to retrieve and edit the mix plan. Because of the browser’s requirement for SharedArrayBuffer and AudioWorklet, it requires a secure context (HTTPS) or a localhost mapping.

B. AudioFlux Showcase (/home/dev/audio/audioflux/) #

An educational MIR platform containing three simultaneous Gradio web applications:

  1. Main App (Port 7860): Classic modular dashboard covering 6 learning modules.
  2. Unified Dashboard (Port 7861): Card-based dashboard with advanced analysis.
  3. MIR Playground (Port 7863): Standalone zero-click analyzer (mir_playground_standalone.py).

Core Tech & Math: Python 3.11, Gradio Blocks, custom NumPy/SciPy audio processing (onset detection via spectral flux, autocorrelation pitch tracking, inter-onset interval tempo analysis). Strictly no external AudioFlux or librosa package dependencies to ensure lightweight, predictable math.

C. Hugdown / GIGO Project (/home/dev/hugdown/) #

A hybrid React-Hugo hydration framework/site split into:

  1. GOMA (Port 55211): Hugo static site generator serving as the backend and JSON API generator.
  2. GIMA (Port 55220): Vite React frontend.
  3. LiveReload (Port 55212): Development server live reloading agent.

Integration Patterns:

  • Pattern 1 (Shortcode Hydration): Hugo layouts fetch client-side React components through standard HTML import maps linking to CDN-based React/ReactDOM (on esm.sh). Allows React components to hydrate dynamically inside static Hugo pages.
  • Pattern 3 (API-First): Vite React app fetches a JSON index of posts (/posts/index.json) generated by Hugo to render interactive card/poster layouts dynamically.
  • Pattern 4 (Hybrid Dev Server): Concurrent startup of Vite and Hugo with process monitoring.

D. Langflow Chatbot Workflow Builder (/home/dev/py/flow/) #

A visual chat flow workspace running Langflow:

  • Server Configuration: Runs on Port 55577 (bound to 0.0.0.0 behind proxy https://0rk.de/).
  • Database: SQLite database file langflow.db.
  • Integrations: Langsmith tracing endpoint, OpenRouter API keys, and custom OpenAI/Groq keys defined in /home/dev/py/flow/.env.

E. Groq + Gradio Showcase (/home/dev/py/groqgradio/) #

Gadio chat interfaces and proxies integrated with Groq and Langflow. Deployed as user systemd services:

  • Minimal Chat: Port 55443 (groq-minimal.service). Clean chat interface.
  • Streamlined Experience: Port 55444 (groq-streamlined.service). Single-page streaming.
  • Full Showcase: Port 55441 (groq-main.service). Comprehensive UI showcase.
  • Langflow Chat Proxy: Port 55446 (groq-langflow.service). Connects Gradio frontend with Langflow backend nodes.

F. Jamjams OpenAI Chat Lab (/home/dev/py/gradiomulti/) #

A multimodal OpenAI chat environment integrated via OpenRouter.

  • Server Configuration: Runs on Port 55442.
  • Security: Built-in JWT authentication configuration (JWT_SECRET_KEY on HS256).

G. MUGEN & MUGEN WebUI (/home/dev/py/mugen/ & py/mugen-webui/) #

Music Video Generator (AMV/montage maker) that extracts beats/onsets from audio tracks and automatically cuts video sources to match:

  • py/mugen/: The core library handling rhythm analysis, BeatGroups segmentation, and MoviePy composition.
  • py/mugen-webui/: A Gradio web application (webui.py) serving as a control center for importing video folders, analyzing music tracks, applying video filters, and generating AMV previews.

H. Active Sandbox Repositories (/home/dev/active/) #

A suite of individual active repositories in various domains:

  • ai-town (/home/dev/active/ai-town/): Convex + React multi-agent 2D simulation environment.
  • storymatrix (/home/dev/active/storymatrix/): Automated content production pipeline with YAML-based configurations and output directories.
  • ebay-sniper (/home/dev/active/ebay-sniper/): Automated bidding bot with Python/Docker structure.
  • fun & funday (/home/dev/active/fun/, /home/dev/active/funday/): Node/Express multiplayer test setups with start-funday.sh.
  • daisyui & daisystory (/home/dev/active/daisyui/, /home/dev/active/daisystory/): Tailwind CSS component playgrounds and Storybook configurations.

3. Key Directories #

All paths must be resolved as absolute paths:

  • MixBox Workspace Paths:
    • /home/dev/audio/mixbox/ (Root)
    • /home/dev/audio/mixbox/packages/audio-core/ (Common audio primitives & loader)
    • /home/dev/audio/mixbox/packages/dj-engine/ (DJ automation & NiceGUI views)
    • /home/dev/audio/mixbox/packages/video-gen/ (Video composition & visual effects)
    • /home/dev/audio/mixbox/packages/analyzer/ (MIR analyzer, database & reporting)
    • /home/dev/audio/mixbox/packages/emotion/ (Valence/Arousal MusiCNN classification)
    • /home/dev/audio/mixbox/tests/ (Consolidated Test Suite)
    • /home/dev/audio/mixbox/scripts/ (Rotation Quality Gate & Dev scripts)
    • /home/dev/audio/mixbox/tunes/ (Audio source files for test mixes)
    • /home/dev/audio/mixbox/output/ (Export folder for mixed audio, visualizers & logs)
  • AudioFlux Showcase Paths:
    • /home/dev/audio/audioflux/ (Root)
    • /home/dev/audio/audioflux/app/ (Gradio App Modules)
  • Hugdown/GIGO Paths:
    • /home/dev/hugdown/ (Root)
    • /home/dev/hugdown/goma/ (Hugo backend)
    • /home/dev/hugdown/gima/ (Vite React frontend)
  • Langflow Workspace Paths:
    • /home/dev/py/flow/ (Root)
  • GroqGradio Paths:
    • /home/dev/py/groqgradio/ (Root)
  • MUGEN Workspace Paths:
    • /home/dev/py/mugen/ (Core library root)
    • /home/dev/py/mugen-webui/ (Gradio UI root)
  • Active Project Paths:
    • /home/dev/active/ai-town/ (AI Town simulation)
    • /home/dev/active/storymatrix/ (Storymatrix content engine)
    • /home/dev/active/ebay-sniper/ (eBay automated bidder)
    • /home/dev/active/fun/ & /home/dev/active/funday/ (Game lobby tests)

4. Development Commands #

Always execute commands inside their respective directory roots to prevent environment leaks.

A. MixBox Commands (Root: /home/dev/audio/mixbox/) #

Managed via uv:

# Install and synchronize environment dependencies
uv sync

# Check code style and automatically fix lint issues
uv run ruff check . --fix

# Run unit and integration tests (excludes slow rotation tests)
uv run pytest -m "not rotation"

# Run only specific unit tests
uv run pytest tests/test_grid_alignment.py

# Run micro mixing integration tests
uv run pytest tests/test_micro_mix_integration.py

# Run full rotation tests (processes real files, takes 10+ minutes)
uv run pytest -m rotation

# Run the Quality Gate suite (Afro Mix or Micro Mix)
uv run python scripts/rotation_quality_gate.py micro
uv run python scripts/rotation_quality_gate.py afro

# Overwrite the micro baseline with current run results
uv run python scripts/rotation_quality_gate.py micro --update-baseline

# Launch NiceGUI review dashboard (Port 55644)
uv run python -m mixbox.gui

# Execute audio analyzer on a track
uv run hitscan -i tunes/song.mp3

B. AudioFlux Showcase Commands (Root: /home/dev/audio/audioflux/) #

Managed via local .venv (created with uv):

# Activate environment
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Start all three Gradio applications in the background
python app/main.py &
python app/unified_main.py &
python mir_playground_standalone.py &

# Graceful termination of all Gradio instances
pkill -f "main.py\|unified_main.py\|mir_playground_standalone.py"

# Verify services are running locally
curl http://localhost:7860 && curl http://localhost:7861 && curl http://localhost:7863

# Run comprehensive MIR engine validations
python -c "exec(open('test_comprehensive.py').read())"

C. Hugdown / GIGO Commands (Root: /home/dev/hugdown/) #

Managed via standard bash scripts and Node/npm:

# Start GOMA and GIMA concurrently (logs captured in .logs/)
./gigo-start.sh

# Stop all services gracefully
./gigo-stop.sh

# Build Vite React assets and compile Hugo static files
./build-all.sh

# Deploy generated files to target env (e.g., staging)
./deploy.sh staging

# Run E2E Puppeteer / browser verification suite
node test-e2e.js

D. Langflow Commands (Root: /home/dev/py/flow/) #

Managed via poetry/local environment:

# Start the Langflow backend
poetry run langflow run --host 0.0.0.0 --port 55577

E. Groq + Gradio Commands (Root: /home/dev/py/groqgradio/) # 

# Start Gradio App versions using systemd (user-mode)
systemctl --user start groq-minimal.service
systemctl --user start groq-streamlined.service
systemctl --user start groq-main.service
systemctl --user start groq-langflow.service

# View logs for a service
journalctl --user -u groq-minimal -f

F. MUGEN Commands (Root: /home/dev/py/mugen-webui/) # 

# Run MUGEN Gradio WebUI locally
python webui.py

G. Active Project Commands #

  • ai-town (/home/dev/active/ai-town/): 
    npm install
# Run dev frontend and Convex backend locally
npm run dev
npx convex dev
  • funday (/home/dev/active/funday/): 
    # Start multiplayer lobby server
./start-funday.sh

5. Code Conventions & Common Patterns #

Python Development (MixBox, AudioFlux, Mugen, GroqGradio) #

  • Audio Loading Primitives: In MixBox, never use raw custom loading logic. Import and use load_audio from audio_core. It tries librosa first for precision, falling back to pydub (via pydub-ng) to support broad format compatibility.
  • No External Signal Processing Libraries in AudioFlux: In audio/audioflux/, you MUST use the custom NumPy/SciPy mathematical signal processing routines written inside app/utils/audio_utils.py. Direct imports of librosa or audioflux are forbidden.
  • Config Validation: The MixBox system uses pydantic to validate configuration settings. Any additions to config.yaml must be declared and typed in /home/dev/audio/mixbox/packages/dj-engine/src/mixbox/config/models.py.
  • Asynchronous Loop Safety: FastAPI and NiceGUI routes utilize async/await. Avoid blocking calls in async loops; offload slow file/audio computations using run_in_executor or background worker tasks.

Frontend & Static Site Hydration (Hugdown) #

  • CDN Hydration via Import Maps: In Hugdown Pattern 1, load React and ReactDOM from CDN (https://esm.sh/react@18 and https://esm.sh/react-dom@18) using import maps inside layouts/shortcodes/poster.html. This keeps static page loads lightweight and prevents dependency bundling mismatches.
  • Strict Dev Ports: Ensure that GOMA is bound to 55211, GIMA to 55220, and LiveReload to 55212. Always check port allocation inside vite.config.ts and hugo.toml.

6. Important Files #

  • MixBox:
    • /home/dev/audio/mixbox/pyproject.toml (Master workspace dependencies & Ruff configuration)
    • /home/dev/audio/mixbox/config.yaml (Master runtime config)
    • /home/dev/audio/mixbox/packages/dj-engine/src/mixbox/config/models.py (Pydantic models)
    • /home/dev/audio/mixbox/scripts/rotation_quality_gate.py (Regression analysis)
    • /home/dev/audio/mixbox/docs/ARCHITECTURE.md (Main architecture specification)
  • AudioFlux Showcase:
    • /home/dev/audio/audioflux/PROJECT_SUMMARY.yaml (System overview metadata)
    • /home/dev/audio/audioflux/mir_playground_standalone.py (Standalone MIR launcher)
  • Hugdown/GIGO:
    • /home/dev/hugdown/gigo-start.sh (Process orchestrator)
    • /home/dev/hugdown/goma/hugo.toml (Hugo CORS configurations)
    • /home/dev/hugdown/gima/vite.config.ts (Vite dev port config)
  • Langflow Workspace:
    • /home/dev/py/flow/.env (Credentials & server variables)
    • /home/dev/py/flow/langflow.db (SQLite workflow save states)
  • GroqGradio:
    • /home/dev/py/groqgradio/.env (Port configurations & Groq/Langflow keys)
    • /home/dev/py/groqgradio/deploy-services.sh (Service deployment automation script)

7. Runtime/Tooling Preferences #

  • Package Manager: Use Astral uv exclusively for Python workspaces (like MixBox). Use Poetry for Langflow (py/flow/), and Pip inside virtual environments for standalone Gradio apps (audio/audioflux/, py/groqgradio/).
  • Python Version: Lock and target Python 3.11.
  • Formatting Standards: Ruff enforces a maximum line length of 100 characters. Select lints include: E (pycodestyle errors), F (Pyflakes), B (flake8-bugbear), W (pycodestyle warnings), and I (isort import sorting). Whitespace before ‘:’ (E203) and line length limits (E501) are ignored.
  • Port Allocation Map:
    • 55211: Hugo GOMA
    • 55220: Vite GIMA
    • 55212: LiveReload
    • 55577: Langflow Workspace
    • 55644: MixBox NiceGUI Review Server
    • 55441: Groq Showcase Full
    • 55443: Groq Showcase Minimal
    • 55444: Groq Showcase Streamlined
    • 55446: Groq Showcase Langflow Proxy
    • 55442: Jamjams OpenAI Chat Lab
    • 7860: AudioFlux Main App
    • 7861: AudioFlux Unified App
    • 7863: AudioFlux Playground

8. Testing & QA #

  • MixBox Test Pyramid:
    • Unit Tests: Rapid checks (under 2s) verifying beatgrid snapping, key alignment, etc.
    • Smoke Tests: Validates visualization rendering (headless matplotlib tests), report schema compliance, etc.
    • Integration Tests: Generates mock audio files to execute a short mix pipeline (~5s) to verify structural and volume calculations.
    • Rotation Tests: Heavyweight runs processing full audio mixes (10+ minutes).
    • Custom Markers: @pytest.mark.slow, @pytest.mark.integration, @pytest.mark.rotation, @pytest.mark.perf, @pytest.mark.viz.
  • Quality Gate Metrics: The rotation_quality_gate.py measures and compares current runs to output/rotation/baseline_{mode}.json:
    1. Beat-Phase Correction P95 (ms): Micro $\le 10\text{ ms}$; Afro $\le 260\text{ ms}$.
    2. Clipping Ratio: $\le 0.001$.
    3. Energy Dip (dB): Micro $\le 3\text{ dB}$; Afro $\le 6\text{ dB}$.
    4. Wall-Time Regression: $\le 1.25\times$ baseline.
  • AudioFlux Showcase Validation:
    • Validated using test_comprehensive.py. Zero-click operations require functional validation of the Gradio components when files are dynamically fed into the pipeline.
  • Hugdown E2E Verification:
    • Verified by running automated E2E browser tests using Puppeteer (test-e2e.js) to validate CORS JSON integrations, HTML shortcode hydration, and theme renderers.