{"id":46305053,"url":"https://github.com/ace-step/ACE-Step-ComfyUI","last_synced_at":"2026-03-18T07:00:42.957Z","repository":{"id":341205703,"uuid":"1157537379","full_name":"ace-step/ACE-Step-ComfyUI","owner":"ace-step","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-01T10:35:28.000Z","size":44,"stargazers_count":31,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-02T10:09:05.849Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ace-step.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-02-13T23:49:49.000Z","updated_at":"2026-03-02T06:29:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ace-step/ACE-Step-ComfyUI","commit_stats":null,"previous_names":["ace-step/ace-step-comfyui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ace-step/ACE-Step-ComfyUI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace-step%2FACE-Step-ComfyUI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace-step%2FACE-Step-ComfyUI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace-step%2FACE-Step-ComfyUI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace-step%2FACE-Step-ComfyUI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ace-step","download_url":"https://codeload.github.com/ace-step/ACE-Step-ComfyUI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ace-step%2FACE-Step-ComfyUI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30654902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-18T02:48:56.676Z","status":"ssl_error","status_checked_at":"2026-03-18T02:48:55.747Z","response_time":104,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-03-04T12:00:38.868Z","updated_at":"2026-03-18T07:00:42.930Z","avatar_url":"https://github.com/ace-step.png","language":"Python","funding_links":[],"categories":["Workflows trending in 7 days"],"sub_categories":[],"readme":"# ACE-Step-ComfyUI\n\nComfyUI nodes for [ACE-Step](https://acemusic.ai) AI music generation — text-to-music, cover/remix, repaint, and LLM-powered sample generation.\n\n## Installation\n\n### Via ComfyUI Manager\n\nSearch for **ACE-Step-ComfyUI** in ComfyUI Manager and install.\n\n### Manual Installation\n\n```bash\ncd ComfyUI/custom_nodes\ngit clone https://github.com/ace-step/ACE-Step-ComfyUI.git\ncd ACE-Step-ComfyUI\npip install -r requirements.txt\n```\n\nRestart ComfyUI after installation.\n\n## Setup\n\n### Cloud Mode (default)\n\n1. Get your API key from [acemusic.ai/api-key](https://acemusic.ai/api-key)\n2. In the **Text2music Server** node, set **mode** → `cloud` and paste your key into **api_key**\n3. Or set the environment variable `ACESTEP_API_KEY`\n\n\u003e The key is auto-saved locally (in `.config/` under the node directory) and displayed as `●●●●` for security. It is **not** stored in workflow JSON.\n\n### Local Mode\n\nLocal mode lets you run the ACE-Step inference server on your own machine (requires a GPU with sufficient VRAM).\n\n**1. Install ACE-Step 1.5**\n\n```bash\ngit clone https://github.com/ace-step/ACE-Step-1.5.git\ncd ACE-Step-1.5\n```\n\nInstall dependencies (choose one):\n\n```bash\n# Using uv (recommended)\nuv sync\n\n# Or using pip\npip install -e .\n```\n\n**2. Start the local server**\n\n```bash\n# Using uv\nuv run acestep-openrouter --host 0.0.0.0 --port 8002\n\n# Or if installed via pip\nacestep-openrouter --host 0.0.0.0 --port 8002\n```\n\nThe server will download model weights on first launch and then listen on `http://127.0.0.1:8002`.\n\n**3. Configure ComfyUI**\n\nIn the **Text2music Server** node, set **mode** → `local`. The URL auto-fills to `http://127.0.0.1:8002` and the **api_key** field is hidden since no key is needed locally.\n\n## Usage Guide\n\nDrag `workflows/text2music.json` into ComfyUI to load the ready-to-use workflow.\n\n```\n                             ┌── refer_audio ──┐\nLoad Audio (refer) ──────────┘                 │\n                                               ▼\n                            Text2music Gen Params ── gen_params ──► Text2music Server ──► Save Audio\n                                               ▲                          ▲          │\nLoad Audio (src) ──── src_audio ───────────────┘                   Settings ┘      Show Text\nAudio Codes ────────── audio_codes ────────────┘\n```\n\n### Quick Start: Text-to-Music\n\n1. Open the workflow. **sample_mode** is OFF by default — you are in manual mode.\n2. Fill in **caption** (music style description) and **lyrics** (with `[verse]`, `[chorus]` tags). Leave lyrics empty for instrumental.\n3. Click **Queue Prompt**. The generated audio appears in **Save Audio** and generation info in **Show Text**.\n\n### Sample Mode (LLM Auto-Generation)\n\nInstead of writing caption and lyrics yourself, let the LLM generate everything from a simple description:\n\n1. Toggle **sample_mode** → ON in the Gen Params node.\n2. Fill in **sample_query** (e.g. `\"a funk rock song with groovy bass and punchy drums\"`).\n3. Choose **vocal_language** and set **is_instrumental** if you want instrumental only.\n4. Click **Queue Prompt**. The LLM generates caption, lyrics, bpm, key, duration, and time signature automatically, then synthesizes the music.\n\n\u003e In sample mode, only three fields are shown: `sample_query`, `vocal_language`, and `is_instrumental`. All other parameters are decided by the LLM.\n\n### Manual Mode Controls\n\nWhen **sample_mode** is OFF, you have full manual control:\n\n| Field | Description |\n|-------|-------------|\n| **caption** | Music style / genre description |\n| **lyrics** | Song lyrics (empty = instrumental) |\n| **vocal_language** | Language for vocals |\n| **auto** | ON (default): let the LM decide bpm, key, duration, time signature. OFF: set them manually below. |\n| **bpm** | Beats per minute (shown when auto=OFF) |\n| **key** | Musical key, e.g. `C major` (shown when auto=OFF) |\n| **duration** | Duration in seconds (shown when auto=OFF) |\n| **time_signature** | e.g. `4`, `3`, `6` (shown when auto=OFF) |\n| **is_repaint** | Enable repaint mode (see below) |\n| **cover_strength** | Noise injection strength for cover (0 = clean cover) |\n| **remix_strength** | How much original audio to preserve (1.0 = full) |\n\n### Cover / Remix Mode\n\n1. Load the source song via **Load Audio** and connect it to Gen Params → `src_audio`.\n2. Alternatively, connect pre-extracted audio codes via **Audio Codes** → Gen Params → `audio_codes`.\n3. The task type automatically switches to `cover` when `src_audio` or `audio_codes` is connected.\n4. Adjust **cover_strength** and **remix_strength** to control the output.\n\n\u003e The server automatically converts source audio to audio codes internally when needed. The generated `audio_codes` are also returned as a third output of Text2music Server.\n\n### Repaint Mode\n\n1. Connect source audio to Gen Params → `src_audio`.\n2. Toggle **is_repaint** → ON. The **repaint_start** and **repaint_end** fields appear.\n3. Set the time range (in seconds) for the region to regenerate.\n4. Fill in **caption** and **lyrics** for the regenerated section.\n\n### Reference Audio\n\nConnect a reference audio file to Gen Params → `refer_audio` to guide the style and timbre of the generated music. This works with any mode.\n\n### Settings Node\n\nThe **Settings** node controls inference hyperparameters:\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| **seed** | `-1` | Random seed (`-1` = random, set a number for reproducibility) |\n| **thinking** | `true` | Enable 5Hz LM audio code generation (higher quality, slower) |\n| **use_cot_caption** | `true` | LM chain-of-thought for caption refinement |\n| **use_cot_language** | `true` | LM chain-of-thought for language detection |\n| **temperature** | `0.85` | Sampling temperature |\n| **lm_cfg_scale** | `1.0` | LM classifier-free guidance scale |\n| **dit_guidance_scale** | `3.5` | DiT guidance scale |\n| **dit_inference_steps** | `60` | Number of DiT denoising steps |\n\n## Node Reference\n\n| Node | Description | Inputs | Outputs |\n|------|-------------|--------|---------|\n| **Text2music Gen Params** | Build generation parameters. Supports sample_mode (LLM auto) and manual mode. | `sample_mode`, `vocal_language`, + optional fields | `gen_params` |\n| **Settings** | Inference hyperparameters for LM + DiT. | `seed`, `thinking`, `temperature`, etc. | `settings` |\n| **Text2music Server** | Calls the ACE-Step API to generate music. | `gen_params`, `settings`, `server_url`, `api_key`, `mode` | `audio`, `info`, `audio_codes` |\n| **Audio Codes** | Editable passthrough for audio codes. Paste manually or receive from Text2music Server. | `audio_codes_in` (optional) | `audio_codes` |\n| **Show Text** | Displays any STRING input as a read-only text area. | `text` | `text` (passthrough) |\n\n## Tips\n\n- **Cover/Repaint auto-safety:** When the task is `cover` or `repaint`, `thinking`, `use_cot_caption`, and `use_cot_language` are forced to `false` regardless of Settings values — the LM is not used for these tasks.\n- **Auto metas:** When `auto` is ON, the LM infers bpm/key/duration/time_signature. When OFF, your manual values are sent directly.\n- Use **Show Text** nodes connected to `info` outputs to inspect what the server returned (LLM-generated parameters, generation metadata, etc.).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Face-step%2FACE-Step-ComfyUI","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Face-step%2FACE-Step-ComfyUI","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Face-step%2FACE-Step-ComfyUI/lists"}