{"id":50998839,"url":"https://github.com/thedavidweng/openloop","last_synced_at":"2026-06-20T12:03:35.124Z","repository":{"id":354061240,"uuid":"1220700465","full_name":"thedavidweng/OpenLoop","owner":"thedavidweng","description":"Desktop app for local ACE-Step music generation with prompt, lyrics, full controls, playback, and export.","archived":false,"fork":false,"pushed_at":"2026-06-14T22:55:46.000Z","size":7623,"stargazers_count":0,"open_issues_count":24,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T23:06:29.144Z","etag":null,"topics":["ai-music","desktop-app","local-first","macos","music-generation","rust","tauri"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thedavidweng.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-25T08:01:45.000Z","updated_at":"2026-06-14T21:39:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thedavidweng/OpenLoop","commit_stats":null,"previous_names":["thedavidweng/openloop"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/thedavidweng/OpenLoop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedavidweng%2FOpenLoop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedavidweng%2FOpenLoop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedavidweng%2FOpenLoop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedavidweng%2FOpenLoop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thedavidweng","download_url":"https://codeload.github.com/thedavidweng/OpenLoop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thedavidweng%2FOpenLoop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34568743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-music","desktop-app","local-first","macos","music-generation","rust","tauri"],"created_at":"2026-06-20T12:03:34.221Z","updated_at":"2026-06-20T12:03:35.119Z","avatar_url":"https://github.com/thedavidweng.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[简体中文](./README_CN.md)\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./src-tauri/icons/1024x1024.png\" alt=\"OpenLoop app icon\" width=\"160\" height=\"160\" /\u003e\n\n# OpenLoop\n\n**Generate music locally on your Mac.**\n\nAn open-source desktop AI music generator powered by local inference, built for the OpenMusic series.\n\n[![CI](https://github.com/thedavidweng/OpenLoop/actions/workflows/ci.yml/badge.svg)](https://github.com/thedavidweng/OpenLoop/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/thedavidweng/OpenLoop?include_prereleases\u0026label=release)](https://github.com/thedavidweng/OpenLoop/releases)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)\n![Platform](https://img.shields.io/badge/platform-macOS%20%28Apple%20Silicon%29-lightgrey)\n\n![Status](https://img.shields.io/badge/Status-v0.2.1%20Alpha-orange)\n![OpenMusic](https://img.shields.io/badge/OpenMusic-Series-purple)\n\n\u003c/div\u003e\n\n---\n\n## OpenMusic Series\n\n| Project                                              | Purpose                                                                                  | Status       |\n| ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------ |\n| [OpenKara](https://github.com/thedavidweng/OpenKara) | Turn local songs into karaoke tracks with on-device AI stem separation and synced lyrics | Active       |\n| OpenLoop                                             | Generate new music locally from prompts, lyrics, and musical parameters                  | Alpha v0.2.1 |\n\nThe shared philosophy is simple: music tools should be local-first, ownership-friendly, transparent, and useful with the media and hardware you already have.\n\n---\n\n## Why I Built This\n\nAI music tools are powerful, but many of them share the same problems:\n\n1. They require subscriptions.\n2. They send prompts, lyrics, and creative drafts to cloud services.\n3. They hide model behavior behind closed platforms.\n4. They make export, ownership, and reproducibility harder than they should be.\n\n---\n\n## Installation\n\n```bash\nbrew tap thedavidweng/tap \u0026\u0026 brew install --cask openloop\n```\n\nHomebrew automatically adds `openloop` to your PATH and clears macOS quarantine.\n\n### Install from DMG (manual)\n\n1. Download the latest `.dmg` from [Releases](https://github.com/thedavidweng/OpenLoop/releases).\n2. Drag **OpenLoop** to **Applications**.\n3. **First launch:** macOS may show a Gatekeeper warning because the app uses Ad-hoc code signing. Right-click the app and choose **Open**, or run in Terminal:\n   ```bash\n   xattr -cr /Applications/OpenLoop.app\n   ```\n4. Open Settings → \"Add to PATH\" to enable the CLI.\n\n---\n\n## CLI Mode\n\n`openloop` ships with a full CLI in the same binary as the desktop app. Pass any subcommand and it runs headlessly — no GUI needed.\n\n```bash\nopenloop run \"lo-fi warm piano, 90 BPM\"\nopenloop run --model pro --duration 30 --output ~/Music/beat.mp3\nopenloop setup model turbo\nopenloop list --json\nopenloop ps\n```\n\nEvery GUI operation maps to a CLI command. The CLI reads/writes the same SQLite database, so history and settings stay in sync with the app.\n\n### Agent Pipelines\n\nPaired with **[Remotion](https://github.com/remotion-dev/remotion)** (programmatic React video rendering) or **[HyperFrames](https://github.com/heygen-com/hyperframes)** (HTML-to-video), an AI coding agent can orchestrate end-to-end video workflows:\n\n```\nAI agent → openloop run (music) → Remotion / HyperFrames (video) → final render\n```\n\nThe `--json` flag streams machine-readable NDJSON — agents parse one JSON line at a time:\n\n```bash\nopenloop run \"cinematic strings\" --json | while read line; do\n  echo \"Progress: $(echo \"$line\" | jq -r '.event')\"\ndone\n```\n\n[Full CLI documentation →](./docs/cli.md)\n\n---\n\n## Features\n\n### v0.2.1 Alpha\n\n- **Text-to-Music Generation** — Generate music from prompts such as `lo-fi warm piano, 90 BPM, no vocal`.\n- **Lyrics Input** — Add lyrics with optional structure tags like `[verse]`, `[chorus]`, and `[bridge]`.\n- **Local AI Backend** — Run ACE-Step locally through a managed backend process.\n- **Apple Silicon Acceleration** — Use MLX on Apple Silicon with CPU/GPU execution and unified memory.\n- **Duration Control** — Generate clips from short loops to longer song drafts.\n- **BPM, Key, and Time Signature Controls** — Provide musical constraints for generation.\n- **Seed Reproduction** — Reuse a seed to reproduce or iterate on previous results.\n- **Built-in Preview Player** — Play generated audio inside the app.\n- **Waveform Review** — Inspect generated audio with a waveform surface rendered from Rust audio decoding.\n- **Local Generation History** — Store prompt, lyrics, model settings, seed, and output path in a local SQLite database.\n- **Export** — Save generated audio to a local output folder.\n\n### Planned\n\nSee [GitHub issues](https://github.com/thedavidweng/OpenLoop/issues) for the roadmap.\n\n---\n\n## Build from Source\n\n### Prerequisites\n\n- macOS 14+ recommended\n- Apple Silicon Mac recommended\n- Node.js 20+\n- pnpm 11+\n- Rust stable toolchain\n- Tauri 2 platform dependencies\n\n### Clone and run\n\n```bash\ngit clone https://github.com/thedavidweng/OpenLoop.git\ncd OpenLoop\npnpm install\npnpm tauri dev\n```\n\n### Development checks\n\n```bash\npnpm install\npnpm release:check\n```\n\n### Local release build\n\n```bash\npnpm install --frozen-lockfile\npnpm release:build\n```\n\nDetailed manual QA notes live in [`docs/testing.md`](docs/testing.md).\nRelease packaging notes live in [`docs/release.md`](docs/release.md).\n\nFor the current implementation status and more development details, see [Implementation Status](./docs/implementation-status.md).\n\n## System Requirements\n\n| Requirement      | Target                                                                                      |\n| ---------------- | ------------------------------------------------------------------------------------------- |\n| Operating system | macOS 14+ recommended; macOS 12–13 best effort                                              |\n| CPU/GPU          | Apple Silicon recommended                                                                   |\n| Memory           | 8 GB minimum target; 16 GB+ recommended                                                     |\n| Storage          | Several GB for models and generated audio                                                   |\n| Network          | Required for first model/backend setup; offline afterward unless the user chooses otherwise |\n\nIntel Mac support is experimental.\n\n---\n\n## AI Models\n\nOpenLoop uses [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) as the local music generation backend.\n\nThe app targets a profile-based model setup:\n\n| Profile | Target Device        | Default Strategy                             |\n| ------- | -------------------- | -------------------------------------------- |\n| Lite    | 8 GB Apple Silicon   | Conservative settings, lower memory pressure |\n| Turbo   | 16 GB+ Apple Silicon | Recommended default                          |\n| Pro     | 24 GB+ Apple Silicon | Highest quality with XL model and larger LM  |\n\nModel files are downloaded or selected during first setup and stored locally. The application code is Apache 2.0 licensed; model weights and third-party components follow their upstream licenses.\n\n---\n\n## Tech Stack\n\n| Layer                   | Technology                                               | Purpose                                                                                 |\n| ----------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| Desktop framework       | [Tauri 2](https://v2.tauri.app/)                         | Rust backend + system WebView desktop shell                                             |\n| Frontend                | React + TypeScript + Vite                                | App UI, generation form, player, history panel                                          |\n| Backend orchestration   | Rust                                                     | Process management, API proxy, file operations, SQLite                                  |\n| AI backend              | [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) | Local music generation                                                                  |\n| Apple Silicon inference | [MLX](https://github.com/ml-explore/mlx)                 | Apple Silicon CPU/GPU execution and unified memory                                      |\n| Python environment      | bundled `uv` sidecar                                     | Reproducible local backend environment without relying on user-installed Python or `uv` |\n| Database                | SQLite                                                   | Settings, generation history, backend events                                            |\n| Packaging               | Tauri bundler                                            | macOS `.dmg` release                                                                    |\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TB\n  subgraph CLI[\"CLI Mode\"]\n    CLI_ENTRY[\"openloop run/setup/...\"]\n  end\n\n  subgraph UI[\"Tauri GUI\"]\n    H[\"History Sidebar\"]\n    G[\"Generation Form\"]\n    P[\"Playback Bar + Waveform\"]\n  end\n\n  subgraph BE[\"Rust Service Layer\"]\n    BM[\"BackendManager\"]\n    AC[\"AceClient\"]\n    TR[\"GenerationTaskRunner\"]\n    SF[\"FileStore / SQLite\"]\n    WA[\"Waveform (Symphonia)\"]\n  end\n\n  CLI_ENTRY --\u003e BE\n  H --\u003e BE\n  G --\u003e BE\n  P --\u003e BE\n  BM --\u003e AC --\u003e TR --\u003e SF --\u003e API[\"Local ACE-Step API Server\"] --\u003e OUT[\"Local Output Files\u003cbr/\u003eWAV / MP3 / FLAC / OGG\"]\n  P --\u003e WA --\u003e OUT\n```\n\nOpenLoop uses a local API server model — the Rust service layer owns process lifecycle, health checks, task polling, file paths, and error mapping. The same service layer is shared by both GUI and CLI modes.\n\n---\n\n## Data and Privacy\n\nOpenLoop is local-first by design.\n\n- Prompts stay on your Mac.\n- Lyrics stay on your Mac.\n- Generated audio stays on your Mac.\n- History is stored in a local SQLite database.\n- No account system is planned.\n- No telemetry is planned.\n- The app should only use the network for model/backend setup or user-initiated external links.\n\nLogs should avoid storing full lyrics or complete sensitive prompts. Backend errors should be summarized into user-readable messages.\n\n---\n\n## Responsible Use\n\nOpenLoop does not provide legal clearance for generated music.\n\nUsers are responsible for checking whether generated output is appropriate for publication, monetization, or commercial use. Avoid entering protected lyrics, melodies, voices, or prompts that explicitly imitate protected artists or copyrighted works. When publishing generated music, follow applicable laws and platform rules around AI-generated content disclosure.\n\nSee [RESPONSIBLE_USE.md](./RESPONSIBLE_USE.md) for detailed guidelines.\n\n---\n\n## Known Limitations\n\n- Apple Silicon is the primary target. Intel Mac support is experimental.\n- First setup may require a large model download.\n- Generation speed depends heavily on memory, model profile, duration, and inference settings.\n- Repaint is not yet implemented (tracked in [#70](https://github.com/thedavidweng/OpenLoop/issues/70)).\n- The app does not guarantee copyright-free output.\n- The current UI favors local workflow coverage and technical completeness over final visual polish.\n\n---\n\n## Contributing\n\nContributions are welcome once the initial Alpha structure is in place.\n\nRecommended contribution areas:\n\n- macOS packaging\n- Tauri backend process management\n- ACE-Step API integration\n- generation history UX\n- model setup diagnostics\n- low-memory performance testing\n- documentation\n\nBefore opening a large PR, please open an issue describing the proposed change.\n\n---\n\n## License\n\nOpenLoop application code is released under the [Apache License 2.0](LICENSE).\n\nThird-party models, libraries, and tools retain their own licenses. In particular, ACE-Step, MLX, FFmpeg, Tauri, and other dependencies should be reviewed according to their upstream license terms before redistribution.\n\n---\n\n## Acknowledgements\n\nOpenLoop builds on work from the open-source music and local AI ecosystem, including:\n\n- [ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5)\n- [MLX](https://github.com/ml-explore/mlx)\n- [Tauri](https://v2.tauri.app/)\n- The broader open-source audio tooling community\n\nOpenLoop is part of the OpenMusic series by [David Weng](https://github.com/thedavidweng).\n\n## Roadmap\n\nFor the detailed development roadmap and planning documents, see:\n\n- **[Implementation Status](./docs/implementation-status.md)** — Current implementation status and completed milestones\n- **[Testing Guide](./docs/testing.md)** — QA procedures and manual test coverage notes\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthedavidweng%2Fopenloop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthedavidweng%2Fopenloop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthedavidweng%2Fopenloop/lists"}