mlx-audiogen 0.2.0__tar.gz

mlx_audiogen-0.2.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+wheels/
+.venv/
+
+# MLX / ML
+model/
+mlx_model/
+converted/
+*.npz
+*.safetensors
+!tests/fixtures/*.safetensors
+
+# Audio output
+*.wav
+*.mp3
+*.flac
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+
+# MCP / tools
+.serena/
+.claude/
+
+# uv
+uv.lock
+
+# Web UI
+web/node_modules/
+web/dist/
+web/*.tsbuildinfo
+
+# JUCE plugin build
+plugin/build/
+plugin/JUCE/
+
+# Worktrees
+.worktrees/
+
+# Demo/script output
+output/
+
+# Superpowers
+.superpowers/
+
+# Music library exports (user-specific, used for development/training)
+Library.xml
+rekordbox.xml
+
+# Enrichment cache (user-specific)
+enrichment.db

mlx_audiogen-0.2.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024-2026 Jason Vassallo
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mlx_audiogen-0.2.0/PKG-INFO

@@ -0,0 +1,400 @@
+Metadata-Version: 2.4
+Name: mlx-audiogen
+Version: 0.2.0
+Summary: Music and audio generation on Apple Silicon using MLX - MusicGen and Stable Audio Open
+Project-URL: Homepage, https://github.com/jasonvassallo/mlx-audiogen
+Project-URL: Repository, https://github.com/jasonvassallo/mlx-audiogen
+Project-URL: HuggingFace, https://huggingface.co/jasonvassallo
+Author: Jason Vassallo
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: apple-silicon,audio,demucs,mlx,music-generation,musicgen,stable-audio,stem-separation
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: huggingface-hub>=0.27.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: mlx>=0.25.2
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: safetensors>=0.4.0
+Requires-Dist: sentencepiece>=0.2.0
+Requires-Dist: sounddevice>=0.5.0
+Requires-Dist: soundfile>=0.12.0
+Requires-Dist: tokenizers>=0.19.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: transformers>=4.40.0
+Provides-Extra: convert
+Requires-Dist: torch>=2.0.0; extra == 'convert'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: mlx-lm>=0.22.0; extra == 'llm'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110.0; extra == 'server'
+Requires-Dist: python-multipart>=0.0.18; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.27.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+# mlx-audiogen
+
+![CI](https://github.com/jasonvassallo/mlx-audiogen/actions/workflows/ci.yml/badge.svg)
+![Integration](https://github.com/jasonvassallo/mlx-audiogen/actions/workflows/integration.yml/badge.svg)
+
+Text-to-audio generation and stem separation on Apple Silicon using [MLX](https://github.com/ml-explore/mlx). Supports **MusicGen**, **Stable Audio Open**, and **Demucs v4** stem separation.
+
+Runs entirely on-device via Metal GPU — no cloud API needed.
+
+**Full stack:** CLI, HTTP server, React web UI, VST3/AU plugin, Max for Live device, cloud deployment.
+
+## Installation
+
+### pip (recommended)
+
+```bash
+pip install mlx-audiogen          # CLI + audio generation
+pip install mlx-audiogen[server]  # + HTTP server & web UI
+pip install mlx-audiogen[llm]     # + LLM prompt enhancement
+pip install mlx-audiogen[server,llm]  # Everything
+```
+
+### Homebrew
+
+```bash
+brew tap jasonvassallo/tap
+brew install mlx-audiogen              # CLI + server
+brew install mlx-audiogen --with-llm   # + LLM prompt enhancement
+```
+
+### uv
+
+```bash
+uv pip install mlx-audiogen[server]
+```
+
+> **Requires macOS with Apple Silicon** (M1 or later). MLX does not support other platforms.
+
+### Extras
+
+| Extra | What it adds | Key dependency |
+|-------|-------------|----------------|
+| (base) | CLI, audio generation, model auto-download | mlx, numpy, transformers |
+| `[server]` | HTTP server, web UI, async jobs | FastAPI, uvicorn |
+| `[llm]` | AI prompt enhancement, suggestions | mlx-lm (model downloads on first use) |
+| `[convert]` | Convert PyTorch weights to MLX | torch |
+
+## Supported Models
+
+| Model | Variants | Output | Sample Rate | Architecture |
+|-------|----------|--------|-------------|--------------|
+| MusicGen | small, medium, large | Mono | 32 kHz | Autoregressive (T5 + Transformer + EnCodec) |
+| MusicGen Stereo | small, medium, large | Stereo | 32 kHz | Autoregressive (8 codebooks) |
+| MusicGen Melody | base, large | Mono | 32 kHz | Autoregressive + Chroma conditioning |
+| MusicGen Stereo Melody | base, large | Stereo | 32 kHz | Autoregressive (8 codebooks + Chroma) |
+| MusicGen Style | base | Mono | 32 kHz | Autoregressive + MERT style conditioning |
+| Stable Audio Open | small | Stereo | 44.1 kHz | Diffusion (T5 + DiT + Oobleck VAE) |
+| Stable Audio Open | 1.0 | Stereo | 44.1 kHz | Diffusion (larger DiT, dual time conditioning) |
+| HTDemucs (Demucs v4) | htdemucs, htdemucs_6s | 4 or 6 stems | 44.1 kHz | Hybrid U-Net + Cross-Transformer |
+
+Pre-converted MLX weights for all variants are available on [HuggingFace](https://huggingface.co/jasonvassallo).
+
+## Quick Start
+
+```bash
+# Install with server + web UI
+pip install mlx-audiogen[server]
+
+# Generate audio (model auto-downloads on first use)
+mlx-audiogen --model musicgen --prompt "happy upbeat rock song" --seconds 10
+
+# Launch web UI
+mlx-audiogen-app
+
+# See all options
+mlx-audiogen --help
+```
+
+### Melody Conditioning Example
+
+MusicGen melody variants can condition generation on an existing audio file, extracting its pitch contour (chromagram) to guide the output:
+
+```bash
+# Convert a melody variant
+mlx-audiogen-convert --model facebook/musicgen-melody --output ./converted/musicgen-melody
+
+# Generate with melody conditioning
+mlx-audiogen \
+  --model musicgen \
+  --prompt "orchestral arrangement with strings" \
+  --melody my_humming.wav \
+  --seconds 10 \
+  --output orchestral.wav
+```
+
+The `--melody` flag accepts any WAV file. The pipeline extracts a 12-bin chromagram (one-hot pitch class per frame) and uses it as additional cross-attention conditioning alongside the text prompt. Melody variants also work without `--melody` for text-only generation.
+
+### Style Conditioning Example
+
+MusicGen style variants use a frozen MERT audio feature extractor to capture the timbre and texture of a reference audio clip, then guide generation via dual classifier-free guidance:
+
+```bash
+# Convert the style variant (uses audiocraft format, downloads MERT weights)
+mlx-audiogen-convert --model facebook/musicgen-style --output ./converted/musicgen-style
+
+# Generate with style conditioning
+mlx-audiogen \
+  --model musicgen \
+  --prompt "upbeat electronic dance music" \
+  --style-audio reference_track.wav \
+  --style-coef 5.0 \
+  --seconds 10 \
+  --output styled.wav
+```
+
+The `--style-audio` flag accepts any WAV file as a timbre reference. The pipeline uses dual-CFG with three forward passes per step to blend text semantics with audio style. `--style-coef` controls how strongly the text prompt influences the output relative to the style (default: 5.0). Style variants also work without `--style-audio` for text-only generation.
+
+### Stem Separation (Demucs v4)
+
+Separate any audio into drums, bass, vocals, and other stems using the native MLX port of Meta's HTDemucs:
+
+```bash
+# Convert Demucs weights (one-time, requires torch)
+pip install mlx-audiogen[convert]
+mlx-audiogen-convert --model htdemucs --output ./converted/demucs-htdemucs
+```
+
+The pipeline auto-downloads pre-converted weights from [HuggingFace](https://huggingface.co/jasonvassallo/demucs-htdemucs-mlx) if no local weights are found. Inference runs 100% on MLX — PyTorch is only needed for one-time weight conversion.
+
+## HTTP Server
+
+An optional FastAPI server enables integration with the web UI, DAW plugins, Max for Live, or any HTTP client:
+
+```bash
+# Install server dependencies (if not already)
+pip install mlx-audiogen[server]
+
+# Launch app with web UI and auto-discover all converted models
+mlx-audiogen-app
+
+# Or start server with specific models
+mlx-audiogen-server --weights-dir ./converted/musicgen-small --port 8420
+
+# Multiple models (LRU cache keeps the 2 most recently used loaded)
+mlx-audiogen-server \
+  --weights-dir ./converted/musicgen-small \
+  --weights-dir ./converted/stable-audio \
+  --port 8420
+
+# Open browser on launch
+mlx-audiogen-server --weights-dir ./converted/musicgen-small --open
+
+# Remote access (for web UI on other devices or cloud deployment)
+mlx-audiogen-server --weights-dir ./converted/musicgen-small --host 0.0.0.0
+```
+
+### API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/generate` | Submit generation request (returns job ID). Supports `output_mode`: `audio`, `midi`, or `both` |
+| `GET` | `/api/status/{id}` | Poll job status (`queued`/`running`/`done`/`error`) with real-time `progress` (0.0-1.0) |
+| `GET` | `/api/audio/{id}` | Download generated WAV |
+| `GET` | `/api/midi/{id}` | Download generated MIDI (when `output_mode` is `midi` or `both`) |
+| `GET` | `/api/models` | List available models and loading status |
+| `GET` | `/api/jobs` | List all active/recent jobs |
+| `GET` | `/api/health` | Health check for browser heartbeat |
+| `POST` | `/api/suggest` | AI prompt suggestions (analyze prompt + return refined versions) |
+| `POST` | `/api/enhance` | Enhance prompt via local LLM or template fallback |
+| `POST` | `/api/midi-to-prompt` | Convert MIDI file to descriptive text prompt |
+| `POST` | `/api/separate/{id}` | Separate audio into stems (drums/bass/vocals/other) |
+| `GET` | `/api/presets` | List shared presets |
+| `POST` | `/api/presets/{name}` | Save a preset |
+| `GET` | `/api/presets/{name}` | Load a preset |
+| `GET` | `/api/tags` | Tag database for prompt autocomplete |
+| `GET` | `/api/llm/models` | List discovered local LLM models |
+| `POST` | `/api/llm/select` | Select and load an LLM model |
+| `GET` | `/api/memory` | Get prompt memory (history + style profile) |
+| `GET` | `/api/settings` | Get server settings |
+| `POST` | `/api/settings` | Update server settings |
+
+Interactive API docs at `http://localhost:8420/docs` when running.
+
+## Web UI
+
+A React + TypeScript SPA with a dark, DAW-inspired interface:
+
+```bash
+# Development (hot reload, proxies API to :8420)
+cd web && npm install && npm run dev   # http://localhost:3000
+
+# Production (built and served by FastAPI)
+cd web && npm run build
+```
+
+Features:
+- **Generation**: Model selector, prompt textarea with tag autocomplete, model-aware parameter sliders, BPM-based duration mode
+- **AI Enhancement**: Local LLM prompt enhancement with preview (accept/edit/use original)
+- **Suggestions**: Prompt analysis tags (genre, mood, instruments) + refined suggestion cards
+- **Playback**: Web Audio API waveform visualization, BPM-synced looping, time-stretch or vinyl pitch modes
+- **Transport Bar**: DAW-style bottom bar with master BPM, pitch mode, audio device selector, connection status
+- **History**: IndexedDB-persisted generation history with favorites, auto-delete retention, MIDI download
+- **Stem Separation**: Color-coded inline audio players for drums/bass/vocals/other
+- **Presets**: Save/load generation parameter presets
+- **Remote Server**: Connect to a remote mlx-audiogen server (e.g., cloud Mac Mini)
+
+## Native Plugin (VST3 / AU)
+
+A JUCE-based plugin for Ableton Live, Logic Pro, and other DAWs:
+
+```bash
+cd plugin && git submodule update --init  # first time: clone JUCE
+cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release
+# Installs to ~/Library/Audio/Plug-Ins/{VST3,Components}/
+```
+
+Features: auto-server-launch, local/remote server fallback (with Cloudflare Access auth), model auto-discovery, BPM sync, MIDI trigger, A/B/C/D variations, keep/discard workflow, beat-grid trimming, effects chain, Push 2 APVTS compatibility.
+
+## Max for Live Integration
+
+A Node for Max client (`m4l/mlx-audiogen.js`) connects Ableton Live directly to the HTTP server for generating audio from within your session:
+
+1. Start the server (see above)
+2. Load the Max for Live device onto a MIDI track
+3. Type a prompt and click Generate — the WAV is auto-saved and the path is output for drag-to-track
+
+See [`m4l/README.md`](m4l/README.md) for message reference and outlet documentation.
+
+## Requirements
+
+- **macOS with Apple Silicon** (M1 or later) — MLX requires Metal GPU
+- Python 3.11+ (automatically satisfied by pip/brew install)
+
+## CLI Parameters
+
+### Generation (`mlx-audiogen`)
+
+| Parameter | MusicGen | Stable Audio | Default | Description |
+|-----------|:--------:|:------------:|---------|-------------|
+| `--model` | required | required | — | `musicgen` or `stable_audio` |
+| `--prompt` | required | required | — | Text description of desired audio |
+| `--seconds` | yes | yes | 5.0 | Duration (max ~30s for MusicGen, ~47s for Stable Audio) |
+| `--output` | yes | yes | auto | Output WAV file path |
+| `--seed` | yes | yes | random | Random seed for reproducibility |
+| `--weights-dir` | yes | yes | — | Path to converted weights directory |
+| `--temperature` | yes | — | 1.0 | Sampling temperature (higher = more creative) |
+| `--top-k` | yes | — | 250 | Top-k sampling candidates |
+| `--guidance-coef` | yes | — | 3.0 | Classifier-free guidance scale |
+| `--melody` | yes | — | — | Audio file for melody conditioning (melody variants only) |
+| `--style-audio` | yes | — | — | Audio file for style conditioning (style variants only) |
+| `--style-coef` | yes | — | 5.0 | Dual-CFG text influence coefficient (style variants only) |
+| `--steps` | — | yes | 8 | Number of diffusion steps |
+| `--cfg-scale` | — | yes | 6.0 | CFG guidance scale |
+| `--sampler` | — | yes | euler | ODE sampler (`euler` or `rk4`) |
+| `--negative-prompt` | — | yes | "" | Negative prompt for CFG |
+
+### Conversion (`mlx-audiogen-convert`)
+
+| Parameter | Description |
+|-----------|-------------|
+| `--model` | HuggingFace repo ID (e.g., `facebook/musicgen-small`) or Demucs variant (`htdemucs`) |
+| `--output` | Output directory for converted weights |
+| `--dtype` | Optional: `float16`, `bfloat16`, or `float32` |
+| `--trust-remote-code` | Allow non-whitelisted repo IDs |
+
+#### Supported Repos
+
+**MusicGen (mono):** `facebook/musicgen-small`, `facebook/musicgen-medium`, `facebook/musicgen-large`
+
+**MusicGen Stereo:** `facebook/musicgen-stereo-small`, `facebook/musicgen-stereo-medium`, `facebook/musicgen-stereo-large`
+
+**MusicGen Melody:** `facebook/musicgen-melody`, `facebook/musicgen-melody-large`
+
+**MusicGen Stereo Melody:** `facebook/musicgen-stereo-melody`, `facebook/musicgen-stereo-melody-large`
+
+**MusicGen Style:** `facebook/musicgen-style`
+
+**Stable Audio:** `stabilityai/stable-audio-open-small`, `stabilityai/stable-audio-open-1.0`
+
+**Demucs:** `htdemucs`, `htdemucs_6s`
+
+> **Note:** Some HF repos (musicgen-medium, musicgen-large) only provide `pytorch_model.bin` files instead of safetensors. The converter handles both formats automatically, but PyTorch must be installed (`pip install mlx-audiogen[convert]`).
+
+> **Note:** `stabilityai/stable-audio-open-1.0` is a gated model. You must accept the license agreement on the [HuggingFace model page](https://huggingface.co/stabilityai/stable-audio-open-1.0) before converting.
+
+## Architecture
+
+```
+mlx_audiogen/
+├── shared/           # T5 encoder, EnCodec, hub utils, audio I/O, MIDI, stem separation
+├── models/
+│   ├── musicgen/     # Autoregressive: T5 -> transformer -> EnCodec decode
+│   │   ├── chroma.py # Chromagram extraction for melody conditioning
+│   │   ├── mert.py   # MERT feature extractor for style conditioning
+│   │   └── style_conditioner.py  # Style transformer + RVQ + BatchNorm
+│   ├── stable_audio/ # Diffusion: T5 -> DiT (rectified flow) -> VAE decode
+│   └── demucs/       # Source separation: HTDemucs v4 (hybrid U-Net + cross-transformer)
+├── server/           # FastAPI HTTP server with LRU pipeline cache
+├── cli/              # Unified CLI for generation and conversion
+web/                  # React + Vite + TypeScript SPA (dark/pro audio UI)
+plugin/               # JUCE native VST3/AU plugin
+m4l/                  # Max for Live Node.js HTTP client for Ableton
+```
+
+**MusicGen**: Text -> T5 encode -> autoregressive transformer with KV cache + classifier-free guidance + codebook delay pattern -> top-k sampling -> EnCodec decode -> 32kHz WAV
+
+**MusicGen Melody**: Text -> T5 encode + chromagram from audio -> cross-attention conditioning -> same pipeline as above
+
+**MusicGen Style**: MERT extracts features from reference audio -> style transformer + RVQ -> dual-CFG with 3 forward passes per step (full, style-only, unconditional) -> same decode pipeline
+
+**Stable Audio**: Text -> T5 encode + time conditioning -> rectified flow ODE sampling through DiT -> Oobleck VAE decode -> 44.1kHz stereo WAV
+
+**HTDemucs (Demucs v4)**: Stereo 44.1kHz audio -> STFT -> complex-as-channels -> instance normalize -> parallel spectral U-Net + temporal U-Net with DConv residual branches -> CrossTransformerEncoder (5 layers, alternating self-attention and cross-attention) -> parallel decoder U-Nets with skip connections -> CaC mask + iSTFT + temporal denormalize -> 4 stems (drums, bass, other, vocals)
+
+## Development
+
+```bash
+# Clone and install in development mode
+git clone https://github.com/jasonvassallo/mlx-audiogen
+cd mlx-audiogen
+uv sync
+
+# Run from source
+uv run mlx-audiogen --model musicgen --prompt "test" --seconds 5
+
+# Run tests
+uv run pytest                                     # all tests (512 tests, ~14s)
+uv run pytest -m integration -v                   # integration tests (real weights + GPU)
+uv run pytest tests/test_specific.py::test_name   # single test
+
+# Lint
+uv run ruff check .
+uv run ruff format .
+
+# Type checking
+uv run mypy mlx_audiogen/
+
+# Security audit
+uv run bandit -r mlx_audiogen/ -c pyproject.toml
+uv run pip-audit
+```
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).
+
+## Links
+
+- [GitHub](https://github.com/jasonvassallo/mlx-audiogen)
+- [HuggingFace](https://huggingface.co/jasonvassallo)
+- [Demucs MLX Weights](https://huggingface.co/jasonvassallo/demucs-htdemucs-mlx)
+- [MusicGen paper](https://arxiv.org/abs/2306.05284)
+- [Stable Audio Open paper](https://arxiv.org/abs/2407.14358)
+- [Demucs v4 paper](https://arxiv.org/abs/2211.08553)