canturia 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- canturia-0.1.0/.gitignore +28 -0
- canturia-0.1.0/CLAUDE.md +71 -0
- canturia-0.1.0/LICENSE +21 -0
- canturia-0.1.0/PKG-INFO +204 -0
- canturia-0.1.0/README.md +171 -0
- canturia-0.1.0/SPEC.md +266 -0
- canturia-0.1.0/pyproject.toml +142 -0
- canturia-0.1.0/src/canturia/__init__.py +3 -0
- canturia-0.1.0/src/canturia/__main__.py +4 -0
- canturia-0.1.0/src/canturia/cli.py +511 -0
- canturia-0.1.0/src/canturia/config.py +276 -0
- canturia-0.1.0/src/canturia/core.py +271 -0
- canturia-0.1.0/src/canturia/providers/__init__.py +17 -0
- canturia-0.1.0/src/canturia/providers/acestep.py +365 -0
- canturia-0.1.0/src/canturia/serve.py +538 -0
- canturia-0.1.0/src/canturia/serve_page.html +598 -0
- canturia-0.1.0/tests/test_acestep.py +291 -0
- canturia-0.1.0/tests/test_cli.py +91 -0
- canturia-0.1.0/tests/test_config.py +91 -0
- canturia-0.1.0/tests/test_core.py +169 -0
- canturia-0.1.0/tests/test_serve.py +213 -0
- canturia-0.1.0/uv.lock +1749 -0
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
.venv/
|
|
6
|
+
build/
|
|
7
|
+
dist/
|
|
8
|
+
.pytest_cache/
|
|
9
|
+
.ruff_cache/
|
|
10
|
+
.coverage
|
|
11
|
+
htmlcov/
|
|
12
|
+
|
|
13
|
+
# AppleDouble files on exFAT
|
|
14
|
+
._*
|
|
15
|
+
|
|
16
|
+
# Local config and output
|
|
17
|
+
canturia.yaml
|
|
18
|
+
.canturia.yaml
|
|
19
|
+
songs/
|
|
20
|
+
output/
|
|
21
|
+
*.mp3.tmp
|
|
22
|
+
|
|
23
|
+
# Tauri / Rust
|
|
24
|
+
desktop/src-tauri/target/
|
|
25
|
+
desktop/src-tauri/gen/
|
|
26
|
+
|
|
27
|
+
# OS
|
|
28
|
+
.DS_Store
|
canturia-0.1.0/CLAUDE.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Canturía — agent handover
|
|
2
|
+
|
|
3
|
+
`SPEC.md` is the source of truth. This file is the short working note.
|
|
4
|
+
|
|
5
|
+
## What it is
|
|
6
|
+
|
|
7
|
+
A privacy-first **text-to-song** tool: paste lyrics or describe a topic, choose
|
|
8
|
+
a genre and a length, get an MP3 from an ACE-Step 1.5 server you point it at.
|
|
9
|
+
Same shape as Limn: Python core + Typer CLI + FastAPI single page + Tauri v2
|
|
10
|
+
shell. PyPI package and CLI: `canturia`.
|
|
11
|
+
|
|
12
|
+
## Status (0.1.0)
|
|
13
|
+
|
|
14
|
+
- Python core, ACE-Step client, CLI, web UI, password gate, tests — done and
|
|
15
|
+
verified live against `http://192.168.20.120:8002` (lyrics mode).
|
|
16
|
+
- Tauri shell, icons, `cargo check`, CI workflows — in the repo. No PyPI
|
|
17
|
+
release yet, so the desktop sidecar needs `CANTURIA_DEV_PATH` for dev.
|
|
18
|
+
- **Describe mode is untested live** because the server currently reports
|
|
19
|
+
`llm_initialized: false`. It uses `sample_mode`/`sample_query`; enable the
|
|
20
|
+
server's LM (`resident: true` in `puente.yml`) to use it.
|
|
21
|
+
- 41 tests, ruff clean, basedpyright 0 errors.
|
|
22
|
+
|
|
23
|
+
## Local commands
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/canturia" # repo is on exFAT
|
|
27
|
+
uv sync --all-groups
|
|
28
|
+
uv run --no-sync ruff check src tests
|
|
29
|
+
uv run --no-sync basedpyright
|
|
30
|
+
uv run --no-sync pytest
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Live smoke test:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
uv run --no-sync canturia "[Verse]\nMorning light" -g folk -t 10 -o /tmp/x.mp3 \
|
|
37
|
+
--base-url http://192.168.20.120:8002
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## API gotchas (verified)
|
|
41
|
+
|
|
42
|
+
- `query_result` wraps its payload in `{data, code, error, timestamp}`.
|
|
43
|
+
- `data[0].result` is a **JSON string**; decode it again.
|
|
44
|
+
- A finished result's `file` is a ready-made relative URL:
|
|
45
|
+
`/v1/audio?path=%2Fapp%2F...`, **not** a raw path. `AceStepClient.download`
|
|
46
|
+
accepts both a ready URL and a raw path.
|
|
47
|
+
- Failed jobs sometimes have `status: 2` with no reason, and `progress_text`
|
|
48
|
+
is a stale global log line. Never use it as the error; say the lyrics writer
|
|
49
|
+
may be off when Describe failed.
|
|
50
|
+
- `batch_size` defaults to 2; Canturía always sends 1.
|
|
51
|
+
- First cold request downloads ~8 GB of weights; default timeout is 900 s.
|
|
52
|
+
|
|
53
|
+
## Machine gotchas
|
|
54
|
+
|
|
55
|
+
- The repo is on exFAT. Keep the venv on the internal disk
|
|
56
|
+
(`UV_PROJECT_ENVIRONMENT`), and delete AppleDouble `._*` files before Tauri
|
|
57
|
+
builds. `desktop/src-tauri/build.rs` clears them from `capabilities/` and
|
|
58
|
+
`icons/` automatically.
|
|
59
|
+
- Tauri dev needs `CANTURIA_DEV_PATH` until `canturia` is on PyPI; otherwise it
|
|
60
|
+
tries `canturia[serve]==0.1.0`.
|
|
61
|
+
|
|
62
|
+
## Decisions
|
|
63
|
+
|
|
64
|
+
- Two modes: `lyrics` (LM off) and `describe` (LM on).
|
|
65
|
+
- Genre chips + free-text style; length presets + custom 10–600 s.
|
|
66
|
+
- Session gallery in memory; Save to `~/Music/Canturia` + JSON sidecar;
|
|
67
|
+
Download/Again/Delete.
|
|
68
|
+
- Shared app password for hosted `serve`; upstream Bearer/Basic separately.
|
|
69
|
+
- No advanced controls in v1; document BPM/key/time signature/instrumental/
|
|
70
|
+
language/LoRA for later.
|
|
71
|
+
- Build order: CLI + web, then Tauri (both now in the repo).
|
canturia-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Michael Borck
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
canturia-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: canturia
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A small, privacy-first text-to-song tool: lyrics or a topic plus a genre, rendered by your own ACE-Step server.
|
|
5
|
+
Project-URL: Homepage, https://github.com/michael-borck/canturia
|
|
6
|
+
Project-URL: Repository, https://github.com/michael-borck/canturia
|
|
7
|
+
Project-URL: Issues, https://github.com/michael-borck/canturia/issues
|
|
8
|
+
Author-email: Michael Borck <michael.borck@curtin.edu.au>
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: ace-step,ai,cli,music,song-generation,text-to-song
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Multimedia :: Sound/Audio
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Requires-Dist: pyyaml>=6.0.0
|
|
26
|
+
Requires-Dist: requests>=2.31.0
|
|
27
|
+
Requires-Dist: rich>=13.0.0
|
|
28
|
+
Requires-Dist: typer>=0.9.0
|
|
29
|
+
Provides-Extra: serve
|
|
30
|
+
Requires-Dist: fastapi>=0.110.0; extra == 'serve'
|
|
31
|
+
Requires-Dist: uvicorn>=0.29.0; extra == 'serve'
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
# Canturía
|
|
35
|
+
|
|
36
|
+
**Words into a song, rendered by your own ACE-Step server.**
|
|
37
|
+
|
|
38
|
+
Canturía is a small, privacy-first text-to-song tool. Paste lyrics or describe a
|
|
39
|
+
topic, choose a genre and a length, and get an MP3 back. It is the same shape as
|
|
40
|
+
[Limn](https://github.com/michael-borck/limn), but for music: a Python library
|
|
41
|
+
and CLI, a single-page web UI, and (next) a Tauri desktop app.
|
|
42
|
+
|
|
43
|
+
No account, no telemetry, no hosted service. The only network egress is the
|
|
44
|
+
generation request to the ACE-Step server you configure.
|
|
45
|
+
|
|
46
|
+
## Two ways in
|
|
47
|
+
|
|
48
|
+
- **Lyrics** — paste your own words, with `[Verse]` / `[Chorus]` tags for
|
|
49
|
+
structure. This works with the ACE-Step language model switched off.
|
|
50
|
+
- **Describe** — give it a topic or a sentence and let ACE-Step write the
|
|
51
|
+
lyrics. This needs the server's 5Hz language model enabled
|
|
52
|
+
(`resident: true` in `puente.yml`); Canturía detects and explains when it is
|
|
53
|
+
off.
|
|
54
|
+
|
|
55
|
+
Both modes take a genre chip or free-text genre, optional style details, and a
|
|
56
|
+
length from 10 to 600 seconds.
|
|
57
|
+
|
|
58
|
+
## Install
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install "canturia[serve]"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
For development:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
uv sync --all-groups
|
|
68
|
+
uv run canturia --help
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Configure
|
|
72
|
+
|
|
73
|
+
Canturía reads `~/.canturia.yaml`, then `./canturia.yaml`, then CLI flags.
|
|
74
|
+
Write a template and edit it once:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
canturia --init-config
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```yaml
|
|
81
|
+
base_url: http://192.168.20.120:8002
|
|
82
|
+
|
|
83
|
+
# Optional upstream auth (Bearer or HTTP Basic):
|
|
84
|
+
# api_key: "${ACESTEP_API_KEY}"
|
|
85
|
+
# username: admin
|
|
86
|
+
# password: "${ACESTEP_PASSWORD}"
|
|
87
|
+
|
|
88
|
+
timeout: 900 # cold start can take minutes
|
|
89
|
+
poll_interval: 2
|
|
90
|
+
genre: folk
|
|
91
|
+
duration: 30
|
|
92
|
+
|
|
93
|
+
serve:
|
|
94
|
+
host: 127.0.0.1
|
|
95
|
+
port: 2268
|
|
96
|
+
# password: "${CANTURIA_SERVE_PASSWORD}"
|
|
97
|
+
out_dir: ~/Music/Canturia
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Secrets can be referenced as `${VAR}` so no plaintext keys live in the file.
|
|
101
|
+
The same settings are available as `CANTURIA_BASE_URL`,
|
|
102
|
+
`CANTURIA_API_KEY`, `CANTURIA_USERNAME`, `CANTURIA_PASSWORD`, and for the web
|
|
103
|
+
server `CANTURIA_SERVE_PASSWORD`.
|
|
104
|
+
|
|
105
|
+
## CLI
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
# Lyrics mode (the default command)
|
|
109
|
+
canturia "[Verse]\nMorning light across the floor\n[Chorus]\nGrow a little every day" \
|
|
110
|
+
-g folk -t 30 -o morning.mp3
|
|
111
|
+
|
|
112
|
+
# Read lyrics from a file ('-' for stdin)
|
|
113
|
+
canturia --lyrics-file words.txt -g indie -t 60
|
|
114
|
+
|
|
115
|
+
# Describe mode: ACE-Step writes the lyrics (requires its LM)
|
|
116
|
+
canturia describe "a warm song about growing up by the sea" -g folk -t 45
|
|
117
|
+
|
|
118
|
+
# Check the server and whether the lyrics writer is on
|
|
119
|
+
canturia health
|
|
120
|
+
|
|
121
|
+
# Web UI
|
|
122
|
+
canturia serve
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Every saved song gets a `<song>.json` sidecar with the mode, genre, style,
|
|
126
|
+
prompt, lyrics, duration, and server metadata.
|
|
127
|
+
|
|
128
|
+
## Web UI
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
canturia serve --password "something" --host 0.0.0.0
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The page has Lyrics and Describe tabs, genre chips, length presets plus a
|
|
135
|
+
custom field, a style-details field, and a session gallery with an audio player,
|
|
136
|
+
Save, Download, Again, and Delete. The gallery is in memory only; Save writes
|
|
137
|
+
into `~/Music/Canturia` (or `serve.out_dir`).
|
|
138
|
+
|
|
139
|
+
When `serve` binds beyond localhost without a password, it generates one and
|
|
140
|
+
prints it. The upstream ACE-Step credentials are separate: use `api_key` for a
|
|
141
|
+
Bearer token or `username`/`password` for HTTP Basic at a reverse proxy.
|
|
142
|
+
|
|
143
|
+
## ACE-Step notes
|
|
144
|
+
|
|
145
|
+
- The API is asynchronous: `POST /release_task`, poll `POST /query_result`,
|
|
146
|
+
then download `GET /v1/audio?path=...`.
|
|
147
|
+
- `query_result` nests a JSON **string** inside `data[0].result`; Canturía
|
|
148
|
+
decodes it to find the generated file path.
|
|
149
|
+
- Canturía always sends `batch_size: 1`, so one Generate makes one song.
|
|
150
|
+
- The first cold request can download ~8 GB of weights. The default timeout is
|
|
151
|
+
15 minutes; raise it if your first run is slower.
|
|
152
|
+
- The server runs either the Gradio UI or the API, not both. This client needs
|
|
153
|
+
the API mode.
|
|
154
|
+
|
|
155
|
+
## Desktop
|
|
156
|
+
|
|
157
|
+
The Tauri v2 shell lives in `desktop/`. It bootstraps a private Python runtime
|
|
158
|
+
with `uv`, runs `canturia serve` on a random localhost port, and shows the web
|
|
159
|
+
UI in the window. Settings writes `~/.canturia.yaml`.
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
export CANTURIA_DEV_PATH="$PWD" # until the first PyPI release
|
|
163
|
+
cargo install tauri-cli --locked
|
|
164
|
+
cd desktop && cargo tauri dev
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Why Python, and why Tauri
|
|
168
|
+
|
|
169
|
+
Python is the core because the same code is the PyPI library, the CLI, and the
|
|
170
|
+
local server the desktop app runs. Tauri wraps that server with the OS webview,
|
|
171
|
+
so there is no bundled browser engine; Electron would only add weight. The
|
|
172
|
+
desktop app bootstraps a private runtime with `uv`, exactly like Limn, rather
|
|
173
|
+
than shipping a 1 GB Python bundle.
|
|
174
|
+
|
|
175
|
+
## Development
|
|
176
|
+
|
|
177
|
+
On this machine the repo is on an exFAT drive, so keep the venv on the internal
|
|
178
|
+
disk (the same workaround Limn uses):
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/canturia"
|
|
182
|
+
uv sync --all-groups
|
|
183
|
+
uv run --no-sync ruff check src tests
|
|
184
|
+
uv run --no-sync basedpyright
|
|
185
|
+
uv run --no-sync pytest
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Roadmap
|
|
189
|
+
|
|
190
|
+
- **M1** — Python core, CLI, web UI (done).
|
|
191
|
+
- **M2** — Tauri desktop shell with a Settings sheet for the server URL and
|
|
192
|
+
credentials, uv-bootstrapped sidecar, installers in CI (shell and CI in this
|
|
193
|
+
repo; the sidecar installs from PyPI once `canturia` is published).
|
|
194
|
+
- **M3** — Optional advanced controls, documented but hidden by default: BPM,
|
|
195
|
+
key, time signature, instrumental, vocal language, LoRA selection.
|
|
196
|
+
|
|
197
|
+
## Name
|
|
198
|
+
|
|
199
|
+
**Canturía** (Spanish): the act or manner of singing — *"esta composición tiene
|
|
200
|
+
buena canturía."* Package and CLI: `canturia`.
|
|
201
|
+
|
|
202
|
+
## License
|
|
203
|
+
|
|
204
|
+
MIT.
|
canturia-0.1.0/README.md
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# Canturía
|
|
2
|
+
|
|
3
|
+
**Words into a song, rendered by your own ACE-Step server.**
|
|
4
|
+
|
|
5
|
+
Canturía is a small, privacy-first text-to-song tool. Paste lyrics or describe a
|
|
6
|
+
topic, choose a genre and a length, and get an MP3 back. It is the same shape as
|
|
7
|
+
[Limn](https://github.com/michael-borck/limn), but for music: a Python library
|
|
8
|
+
and CLI, a single-page web UI, and (next) a Tauri desktop app.
|
|
9
|
+
|
|
10
|
+
No account, no telemetry, no hosted service. The only network egress is the
|
|
11
|
+
generation request to the ACE-Step server you configure.
|
|
12
|
+
|
|
13
|
+
## Two ways in
|
|
14
|
+
|
|
15
|
+
- **Lyrics** — paste your own words, with `[Verse]` / `[Chorus]` tags for
|
|
16
|
+
structure. This works with the ACE-Step language model switched off.
|
|
17
|
+
- **Describe** — give it a topic or a sentence and let ACE-Step write the
|
|
18
|
+
lyrics. This needs the server's 5Hz language model enabled
|
|
19
|
+
(`resident: true` in `puente.yml`); Canturía detects and explains when it is
|
|
20
|
+
off.
|
|
21
|
+
|
|
22
|
+
Both modes take a genre chip or free-text genre, optional style details, and a
|
|
23
|
+
length from 10 to 600 seconds.
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
pip install "canturia[serve]"
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
For development:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
uv sync --all-groups
|
|
35
|
+
uv run canturia --help
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Configure
|
|
39
|
+
|
|
40
|
+
Canturía reads `~/.canturia.yaml`, then `./canturia.yaml`, then CLI flags.
|
|
41
|
+
Write a template and edit it once:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
canturia --init-config
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```yaml
|
|
48
|
+
base_url: http://192.168.20.120:8002
|
|
49
|
+
|
|
50
|
+
# Optional upstream auth (Bearer or HTTP Basic):
|
|
51
|
+
# api_key: "${ACESTEP_API_KEY}"
|
|
52
|
+
# username: admin
|
|
53
|
+
# password: "${ACESTEP_PASSWORD}"
|
|
54
|
+
|
|
55
|
+
timeout: 900 # cold start can take minutes
|
|
56
|
+
poll_interval: 2
|
|
57
|
+
genre: folk
|
|
58
|
+
duration: 30
|
|
59
|
+
|
|
60
|
+
serve:
|
|
61
|
+
host: 127.0.0.1
|
|
62
|
+
port: 2268
|
|
63
|
+
# password: "${CANTURIA_SERVE_PASSWORD}"
|
|
64
|
+
out_dir: ~/Music/Canturia
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Secrets can be referenced as `${VAR}` so no plaintext keys live in the file.
|
|
68
|
+
The same settings are available as `CANTURIA_BASE_URL`,
|
|
69
|
+
`CANTURIA_API_KEY`, `CANTURIA_USERNAME`, `CANTURIA_PASSWORD`, and for the web
|
|
70
|
+
server `CANTURIA_SERVE_PASSWORD`.
|
|
71
|
+
|
|
72
|
+
## CLI
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
# Lyrics mode (the default command)
|
|
76
|
+
canturia "[Verse]\nMorning light across the floor\n[Chorus]\nGrow a little every day" \
|
|
77
|
+
-g folk -t 30 -o morning.mp3
|
|
78
|
+
|
|
79
|
+
# Read lyrics from a file ('-' for stdin)
|
|
80
|
+
canturia --lyrics-file words.txt -g indie -t 60
|
|
81
|
+
|
|
82
|
+
# Describe mode: ACE-Step writes the lyrics (requires its LM)
|
|
83
|
+
canturia describe "a warm song about growing up by the sea" -g folk -t 45
|
|
84
|
+
|
|
85
|
+
# Check the server and whether the lyrics writer is on
|
|
86
|
+
canturia health
|
|
87
|
+
|
|
88
|
+
# Web UI
|
|
89
|
+
canturia serve
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Every saved song gets a `<song>.json` sidecar with the mode, genre, style,
|
|
93
|
+
prompt, lyrics, duration, and server metadata.
|
|
94
|
+
|
|
95
|
+
## Web UI
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
canturia serve --password "something" --host 0.0.0.0
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The page has Lyrics and Describe tabs, genre chips, length presets plus a
|
|
102
|
+
custom field, a style-details field, and a session gallery with an audio player,
|
|
103
|
+
Save, Download, Again, and Delete. The gallery is in memory only; Save writes
|
|
104
|
+
into `~/Music/Canturia` (or `serve.out_dir`).
|
|
105
|
+
|
|
106
|
+
When `serve` binds beyond localhost without a password, it generates one and
|
|
107
|
+
prints it. The upstream ACE-Step credentials are separate: use `api_key` for a
|
|
108
|
+
Bearer token or `username`/`password` for HTTP Basic at a reverse proxy.
|
|
109
|
+
|
|
110
|
+
## ACE-Step notes
|
|
111
|
+
|
|
112
|
+
- The API is asynchronous: `POST /release_task`, poll `POST /query_result`,
|
|
113
|
+
then download `GET /v1/audio?path=...`.
|
|
114
|
+
- `query_result` nests a JSON **string** inside `data[0].result`; Canturía
|
|
115
|
+
decodes it to find the generated file path.
|
|
116
|
+
- Canturía always sends `batch_size: 1`, so one Generate makes one song.
|
|
117
|
+
- The first cold request can download ~8 GB of weights. The default timeout is
|
|
118
|
+
15 minutes; raise it if your first run is slower.
|
|
119
|
+
- The server runs either the Gradio UI or the API, not both. This client needs
|
|
120
|
+
the API mode.
|
|
121
|
+
|
|
122
|
+
## Desktop
|
|
123
|
+
|
|
124
|
+
The Tauri v2 shell lives in `desktop/`. It bootstraps a private Python runtime
|
|
125
|
+
with `uv`, runs `canturia serve` on a random localhost port, and shows the web
|
|
126
|
+
UI in the window. Settings writes `~/.canturia.yaml`.
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
export CANTURIA_DEV_PATH="$PWD" # until the first PyPI release
|
|
130
|
+
cargo install tauri-cli --locked
|
|
131
|
+
cd desktop && cargo tauri dev
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Why Python, and why Tauri
|
|
135
|
+
|
|
136
|
+
Python is the core because the same code is the PyPI library, the CLI, and the
|
|
137
|
+
local server the desktop app runs. Tauri wraps that server with the OS webview,
|
|
138
|
+
so there is no bundled browser engine; Electron would only add weight. The
|
|
139
|
+
desktop app bootstraps a private runtime with `uv`, exactly like Limn, rather
|
|
140
|
+
than shipping a 1 GB Python bundle.
|
|
141
|
+
|
|
142
|
+
## Development
|
|
143
|
+
|
|
144
|
+
On this machine the repo is on an exFAT drive, so keep the venv on the internal
|
|
145
|
+
disk (the same workaround Limn uses):
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/canturia"
|
|
149
|
+
uv sync --all-groups
|
|
150
|
+
uv run --no-sync ruff check src tests
|
|
151
|
+
uv run --no-sync basedpyright
|
|
152
|
+
uv run --no-sync pytest
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Roadmap
|
|
156
|
+
|
|
157
|
+
- **M1** — Python core, CLI, web UI (done).
|
|
158
|
+
- **M2** — Tauri desktop shell with a Settings sheet for the server URL and
|
|
159
|
+
credentials, uv-bootstrapped sidecar, installers in CI (shell and CI in this
|
|
160
|
+
repo; the sidecar installs from PyPI once `canturia` is published).
|
|
161
|
+
- **M3** — Optional advanced controls, documented but hidden by default: BPM,
|
|
162
|
+
key, time signature, instrumental, vocal language, LoRA selection.
|
|
163
|
+
|
|
164
|
+
## Name
|
|
165
|
+
|
|
166
|
+
**Canturía** (Spanish): the act or manner of singing — *"esta composición tiene
|
|
167
|
+
buena canturía."* Package and CLI: `canturia`.
|
|
168
|
+
|
|
169
|
+
## License
|
|
170
|
+
|
|
171
|
+
MIT.
|