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.
@@ -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
@@ -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.
@@ -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.
@@ -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.