cto-legends · module specification · studio · v0.1.3
legends-stable-audio-3: Hardware-Aware Instrumental Audio, SFX & Continuous Mix CLI
Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.
GitHub Repository (https://github.com/avalonreset/legends-stable-audio-3) · Handoff: cto-legends handoff legends-stable-audio-3
legends-stable-audio-3 (executable CLI `legends-sa3`, Python module `legends_sa3`) is a deterministic planning, generation, and audio-assembly toolkit for Stability AI's Stable Audio 3 ecosystem. Rather than treating local weights, hosted REST endpoints, the web studio, the DAW plugin, and post-generation mixing as interchangeable, the module enforces strict surface routing across five distinct execution lanes. It converts creative briefs into structured `TrackType` and `VocalType` metadata prompts, calculates segment counts against hardware VRAM ceilings (ranging from 90–120s on 8 GB GPUs up to 360–380s on 24 GB RTX 4090 class cards), orchestrates resumable local Medium batches or credit-guarded hosted Large REST requests, and assembles multi-hour continuous background beds or full-song sets.
Under the hood, the audio engine avoids monolithic FFmpeg filter graphs that exhaust system memory on multi-hour renders. Instead, `legends_sa3.mixer` and `legends_sa3.production` decode tracks into 32-bit floating-point PCM (`pcm_f32le`) via subprocess pipes, perform frame-level RMS dBFS scanning (100 ms windows against `-50.0 dBFS` active-cue and `-80.0 dBFS` silence thresholds), trim dead-air heads and quiet generated tails, and stream sample-accurate linear or equal-power cosine/sine crossfades directly into the output encoder. For hosted Stable Audio 3 Large operations (`text-to-audio`, `audio-to-audio`, and `inpaint`), the CLI preflights uploaded audio durations (6–380s) and inpaint mask bounds with `ffprobe`, writes a pending recovery receipt containing the `generation_id` immediately upon job submission before polling, verifies SHA-256 checksums on downloaded bytes, and emits a secret-free JSON provenance receipt.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
A raw Frontier LLM in a browser window cannot inspect local CUDA VRAM capacity, validate gated Hugging Face checkpoint trees, preflight input audio durations with `ffprobe`, recover interrupted paid asynchronous REST jobs without double-spending credits, or stream sample-accurate floating-point PCM crossfades across ten hours of generated audio. When asked to build a long-form mix or run Stable Audio 3 cold, a naive LLM hallucinates CLI flags, conflates local Medium with hosted Large parameters, or outputs a brittle one-line FFmpeg `acrossfade` filter graph that crashes on thirty tracks and leaves dead-air gaps between segments.
- VRAM-Calibrated Segment Math & Offline Planning: `legends-sa3 plan` and `production-plan` compute exact track counts, overlap deductions, and target runtimes deterministically on CPU before any GPU allocation or paid API call occurs, scaling single-generation lengths from 90s (8 GB VRAM) to 380s (24 GB VRAM or hosted Large).
- Two-Switch Paid API Gate & Pending-Receipt Recovery: Hosted Large execution (`legends-sa3 large generate`) refuses to run without both `--confirmed-live-credits <n>` and `--confirm-paid`, preflights audio uploads via `ffprobe`, and persists the returned `generation_id` to disk before polling so interrupted runs resume via `legends-sa3 large result` without re-billing.
- RMS dBFS Active-Cue Trimming vs. Dead-Air Overlaps: Generative audio models frequently emit leading or trailing near-silence that ruins uniform crossfades. `legends-sa3 analyze` and `mix --mix-policy active-cue` scan 100 ms PCM frames to strip silence below `-80.0 dBFS` and align incoming transitions at active musical cues (`>= -50.0 dBFS` with `0.25s` padding).
- Streaming Float32 PCM Assembly & Hash-Pinned LoRA Bridge: `arrange` validates per-transition cue sheets (rejecting unpromoted discovery tracks, missing trim reasons, or colliding fades) and streams 32-bit float WAV (`pcm_f32le`) with peak headroom tracking, while `lora-studio` pins Underfit to commit `8a96800a58c0e8b82327fc04ac31c473ed900b73` and verifies its MIT license SHA-256 before execution.
CLI Subcommands & Capability Surface
legends-sa3 doctor | download-model --model medium --output <dir> — Environment Diagnostics & Gated Model Acquisition: Inspects Python, `ffmpeg`, `ffprobe`, PyTorch, CUDA/MPS status, `flash_attn`, detected GPU model, and VRAM capacity, outputting hardware-specific `recommended_track_seconds`. After the user accepts Stability AI's gated terms on Hugging Face, `download-model` fetches `stabilityai/stable-audio-3-medium` and its T5Gemma conditioner without bundling or redistributing weights.legends-sa3 plan --hours <h> --vram-gb <gb> | production-plan --minutes <m> — VRAM-Aware Mix & Hosted Full-Song Planning: Calculates exact segment counts, crossfade deductions, and final durations on CPU without requiring model weights or API keys. `production-plan` plans hosted Large full-song sets at 380 seconds per generation, estimates credit cost against reference pricing, and enforces `runtime_intent` (`approximate`, `minimum`, or `exact`).legends-sa3 prompt --style <str> --count <n> | generate --model-dir <dir> --output <dir> — Structured Prompt Expansion & Resumable Local Medium Batches: Formats free-form style descriptions and optional recipe scaffolds (`lofi-study`, `trip-hop-trance`) with explicit BPM policies (`--bpm` or `--omit-bpm`), instrumental tags (`VocalType: Instrumental`), and negative prompts. `generate` runs local Medium batches with sequential seeds (`--seed-base`), optional native `.safetensors` LoRA/DoRA checkpoints (`--lora-ckpt-path`, `--lora-strength`), and automatic master assembly.legends-sa3 large plan | large generate --confirmed-live-credits <n> --confirm-paid | large result --generation-id <id> — Guarded Hosted Large REST Client & Idempotent Polling: Supports hosted Stable Audio 3 Large `text-to-audio`, `audio-to-audio`, and `inpaint` operations. Preflights input audio duration (6–380s) and mask boundaries with `ffprobe`, writes a pending JSON receipt immediately after submission, never retries paid POST requests, and recovers interrupted downloads via `large result` with SHA-256 verification.legends-sa3 analyze --input-dir <dir> | mix --mix-policy active-cue | arrange --plan <json> --output <wav> — Active-Cue Signal Analysis & Streaming MP3/WAV Assembly: Decodes source tracks via `ffmpeg` into `f32le` numpy buffers to measure peak/RMS dBFS, leading/trailing silence, and usable cue boundaries. `mix` streams linear crossfades with `--quality-gate` (`warn`, `fail`, `off`) into `320k` stereo MP3 plus a JSON manifest, while `arrange` renders per-pair `linear` or `equal-power` transitions from a reviewed JSON cue sheet to 32-bit float WAV.legends-sa3 lora-studio install | status | start | import <safetensors> | list-adapters — Commit-Pinned Underfit LoRA Studio Bridge: Manages custom Stable Audio 3 adapter training through a security-verified checkout of `dada-bots/underfit` pinned to commit `8a96800a58c0e8b82327fc04ac31c473ed900b73` and license SHA-256 `073a815ba79b8f629ef29f6a0699c14233fe18ae40daea8245941bb410bc8a09`. Imports trained `.safetensors` checkpoints into `.legends/adapters` with SHA-256 manifests and ready-to-run `--lora-ckpt-path` hints.
Raw Frontier LLM vs. legends-stable-audio-3 Execution Matrix
- Surface & Model Routing: Raw LLM (Blurs local Medium, hosted Large REST, web studio Full Mix/Multi-Track, and DAW plugin capabilities into generic advice.) vs. Module (Explicitly separates 5 surfaces (`medium-local`, `large-rest`, `web-studio`, `daw-plugin`, `downstream-mixer-daw`) and refuses silent substitution.) — `legends-sa3 skill validate` and `legends-sa3 doctor` verify local backend readiness vs. hosted REST parameters.
- Paid API Execution & Recovery: Raw LLM (Emits raw `curl` snippets that expose API keys in shell history, lack upload preflight checks, and re-bill on timeout.) vs. Module (Requires `STABILITY_API_KEY` in env, `--confirmed-live-credits`, and `--confirm-paid`; writes pending receipt with `generation_id` before polling.) — `legends-sa3 large plan` dry-runs payload and `ffprobe` bounds; `large result` resumes polling and records output `sha256`.
- Long-Duration Audio Mixing: Raw LLM (Generates massive single-command FFmpeg `acrossfade` filter chains that fail on large track counts and crossfade over dead air.) vs. Module (Decodes one track at a time to `pcm_f32le`, trims quiet heads/tails via 100 ms RMS dBFS analysis, and streams chunks to the encoder.) — `legends-sa3 analyze` outputs per-track cue metrics; `mix` and `arrange` verify duration via `ffprobe` and write `.manifest.json` / `.arrangement.json`.
- Custom LoRA Adapter Supply Chain: Raw LLM (Instructs users to clone unverified third-party training repos and pipe remote shell scripts directly into bash.) vs. Module (Pins Underfit to commit `8a96800a...`, verifies origin URL, required files, and MIT license SHA-256 before opt-in `--run-underfit-install`.) — `legends-sa3 lora-studio status` validates git commit and license hash; `import` hashes `.safetensors` into `.legends/adapters`.
- Vocal & Lyric Expectations: Raw LLM (Hallucinates lyric-singing prompts for Stable Audio 3 as if it were a Suno-style vocal song generator.) vs. Module (Enforces `VocalType: Instrumental` and vocal-excluding negative guidance by default; scopes `--allow-vocals` strictly to vocal-like pads/textures.) — `legends-sa3 prompt` prints the resolved positive prompt, BPM policy, and `negative_prompt_status` before generation.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Does legends-stable-audio-3 bundle Stability AI model weights or bypass Hugging Face gating?
- No. The package never mirrors or redistributes gated weights. For local Medium inference, you must accept Stability AI's terms for `stabilityai/stable-audio-3-medium` and the bundled T5Gemma conditioner on Hugging Face, authenticate locally, and run `legends-sa3 download-model --model medium --output <dir>`.
- How does the CLI prevent double-spending credits when a hosted Stable Audio 3 Large job times out?
- `legends-sa3 large generate` requires both `--confirmed-live-credits <n>` and `--confirm-paid`, never retries a paid POST submission, and writes a pending JSON receipt containing the `generation_id` as soon as the job is accepted. If polling is interrupted, `legends-sa3 large result --generation-id <id> --output <file>` resumes result polling without submitting a duplicate paid job.
- What is the difference between `legends-sa3 mix` and `legends-sa3 arrange`?
- `mix` is designed for continuous background beds: it applies uniform crossfades with automated `active-cue` RMS dBFS head/tail trimming and streams directly to stereo MP3 (`320k`). `arrange` is designed for full-song production sets: it validates an explicit JSON cue sheet with per-pair transition lengths, `linear` or `equal-power` curves, and mandatory selection/trim reasons, streaming the output to unclipped 32-bit float WAV (`pcm_f32le`) for downstream mastering.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.