v0

.all-installed-packages.txt

@@ -0,0 +1,110 @@
+addict==2.4.0
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.13.0
+attrs==26.1.0
+babel==2.18.0
+blis==1.3.3
+brotli==1.2.0
+catalogue==2.0.10
+certifi==2026.4.22
+cffi==2.0.0
+charset-normalizer==3.4.7
+click==8.3.3
+cloudpathlib==0.24.0
+confection==1.3.3
+csvw==4.0.0
+curated-tokenizers==0.0.9
+curated-transformers==0.1.1
+cymem==2.0.13
+diskcache==5.6.3
+dlinfo==2.0.0
+docopt==0.6.2
+en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl#sha256=1932429db727d4bff3deed6b34cfc05df17794f4a52eeb26cf8928f7c1a0fb85
+espeakng-loader==0.2.4
+fastapi==0.136.1
+filelock==3.29.0
+fsspec==2026.4.0
+gradio==6.14.0
+gradio_client==2.5.0
+groovy==0.1.2
+h11==0.16.0
+hf-gradio==0.4.1
+hf-xet==1.5.0
+httpcore==1.0.9
+httpx==0.28.1
+huggingface_hub==1.15.0
+idna==3.15
+isodate==0.7.2
+Jinja2==3.1.6
+joblib==1.5.3
+jsonschema==4.26.0
+jsonschema-specifications==2025.9.1
+kokoro==0.9.4
+language-tags==1.3.1
+llama_cpp_python==0.3.23
+loguru==0.7.3
+markdown-it-py==4.2.0
+MarkupSafe==3.0.3
+mdurl==0.1.2
+misaki==0.9.4
+mpmath==1.3.0
+murmurhash==1.0.15
+networkx==3.6.1
+num2words==0.5.14
+numpy==2.4.5
+orjson==3.11.9
+packaging==26.2
+pandas==3.0.3
+phonemizer-fork==3.3.2
+pillow==12.2.0
+preshed==3.0.13
+pycparser==3.0
+pydantic==2.13.4
+pydantic_core==2.46.4
+pydub==0.25.1
+Pygments==2.20.0
+pyparsing==3.3.2
+python-dateutil==2.9.0.post0
+python-multipart==0.0.28
+pytz==2026.2
+PyYAML==6.0.3
+rdflib==7.6.0
+referencing==0.37.0
+regex==2026.5.9
+requests==2.34.2
+rfc3986==1.5.0
+rich==15.0.0
+rpds-py==0.30.0
+safehttpx==0.1.7
+safetensors==0.7.0
+scipy==1.17.1
+segments==2.4.0
+semantic-version==2.10.0
+shellingham==1.5.4
+six==1.17.0
+smart_open==7.6.1
+soundfile==0.13.1
+spacy==3.8.14
+spacy-curated-transformers==0.3.1
+spacy-legacy==3.0.12
+spacy-loggers==1.0.5
+srsly==2.5.3
+starlette==1.0.0
+sympy==1.14.0
+termcolor==3.3.0
+thinc==8.3.13
+tokenizers==0.22.2
+tomlkit==0.14.0
+torch==2.11.0
+tqdm==4.67.3
+transformers==5.8.1
+typer==0.25.1
+typing-inspection==0.4.2
+typing_extensions==4.15.0
+uritemplate==4.2.0
+urllib3==2.7.0
+uvicorn==0.47.0
+wasabi==1.1.3
+weasel==1.0.0
+wrapt==2.1.2

.gitignore

@@ -0,0 +1,229 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+.all-installed-packages
+**/.DS_Store
+archive/
+lolaby.gguf
+lolaby-llama-3b/
+.venv-arm64/
+.venv-spike/
+assets/pipeline.png

LICENSE

@@ -0,0 +1,209 @@
+                                 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 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 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 those 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 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 accept and charge a
+      fee for, or offer to, accept 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 André Oliveira.
+
+   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.
+
+   ----------------------------------------------------------------------
+   Note: This LICENSE covers the Lolaby APPLICATION CODE in this repository
+   only (Gradio app, audio synths, vision wrapper, safety filter, etc.).
+
+   The fine-tuned lyric MODEL referenced by this app lives in a separate
+   Hugging Face repository and is distributed under the Llama 3.2 Community
+   License. See that repository's LICENSE file for those terms.

README.md

@@ -1,17 +1,158 @@
 ---
 title: Lolaby
-emoji: 🐠
-colorFrom: green
-colorTo: gray
+emoji: 🌙
+colorFrom: yellow
+colorTo: blue
 sdk: gradio
-sdk_version: 6.16.0
-python_version: '3.13'
+sdk_version: "5.0.0"
 app_file: app.py
-pinned: false
-license: apache-2.0
-short_description: AI-powered lullabies
+pinned: true
+license: llama3.2
+short_description: AI-powered lullabies.
+tags:
+  - lullaby
+  - children
+  - small-model
+  - llama-cpp
+  - fine-tuned
+  - on-device
+  - hackathon
+  - build-small-2026
+  - backyard-ai
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Lolaby — AI-powered lullabies
 
-Hello
+> *A tiny AI that watches your child's drawings and sings them a personalised lullaby.*
+
+Built for the [Hugging Face **Build Small Hackathon 2026**](https://huggingface.co/build-small-hackathon) · **Backyard AI** track 🏡
+
+**Try it:** [the live Space](https://huggingface.co/spaces/build-small-hackathon/lolaby) · **Demo video:** [60-second walkthrough](placeholder_demo_video_url) · **Model:** [`lolaby-llama-3b` on the Hub](https://huggingface.co/build-small-hackathon/lolaby-llama-3b) · **Field notes:** [the build journal](placeholder_blog_url)
+
+---
+
+## The Problem
+
+My partner's sister is a kindergarten teacher, who runs nap time for fifteen 4-year-olds on a daily basis. Every child wants the same thing at the start of nap: *"sing me a song with my name in it."* She'd love to give each child their own song, drawn from what they actually love that week (a stuffed fox, a new puppy, the rainbow). She doesn't have time, musical expertise nor a tool.
+
+**Lolaby is the tool.** The child shows Lola what they love — either by doodling on screen, or by handing the teacher a paper drawing for her to snap a photo of. The teacher types their name. A small, on-device AI watches the drawing, writes them a lullaby about it, and sings it back — in about a minute.
+
+Everything runs locally. No cloud LLM, no per-song API cost, no children's drawings or names ever leaving the device.
+
+## How it works
+
+![](https://postimg.cc/G44grHt7)
+
+**The drawing is optional.** 
+No canvas drawing AND no upload? ⭢ The form's *What do they love?* field is used instead. 
+Drawing AND typed loves? ⭢ Both inform the song. 
+
+*Lola* (Lolaby's AI character) tells you what she saw between the audio and the lyrics, so you can see how the drawing turned into the song.
+
+## What's inside
+
+| Component        | Model / Library                                    | Where it runs |
+| ---------------- | -------------------------------------------------- | ------------- |
+| Lyric generation | **Llama 3.2 3B**, fine-tuned, via `llama.cpp`      | CPU, locally  |
+| Drawing → words  | **MiniCPM-V 4.6** (1.3B) via `transformers`        | GPU if available, and CPU otherwise (locally) |
+| Stroke fallback  | Pure NumPy color/density analysis                  | CPU, locally  |
+| Singing voice    | **Kokoro 82M**                       | CPU, locally  |
+| Instruments      | Custom DSP synths, built from spectral analysis    | CPU, locally  |
+| Content safety   | Local keyword + intent filter      | CPU, locally  |
+
+**Total parameters across the whole pipeline: well under 32B.** The lyric model is 3B; the vision model is 1.3B; Kokoro is 82M. The synths have zero parameters — they're DSP (Digital Signal Processors).
+
+## Badges
+
+This submission is satisties all six hackathon bonus quests:
+
+- 🔌 **Off the Grid** — **No cloud APIs at runtime.** Every model in the deployed app runs locally. The Anthropic API was used *only at build time* to distill the lyric training dataset (see "Dataset and provenance" below); it is not called when a song is generated.
+- 🎯 **Well-Tuned** — The lyric model is a custom fine-tune of Llama 3.2 3B, [published on the Hub](https://huggingface.co/build-small-hackathon/lolaby-llama-3b). Trained on a 1,500-example dataset built from scratch with mechanical anti-boilerplate gates; 99.4% line uniqueness across the lyric corpus.
+- 🎨 **Off-Brand** — Custom Gradio UI: hand-drawn aesthetic with crayon palette, Fredoka One + Patrick Hand typography, paper-textured cards, character voice via the "Lola" persona that tells you what she saw.
+- 🦙 **Llama Champion** — Lyric inference runs through `llama-cpp-python` (the `llama.cpp` Python binding) on CPU at Q4_K_M quantisation.
+- 📡 **Sharing is Caring** — A full generation trace (drawing → vision → lyric prompt → raw model output → audio render parameters) is [published on the Hub](placeholder_trace_url) so anyone can study how the pipeline composes.
+- 📓 **Field Notes** — [Build journal here](placeholder_blog_url): the dataset rebuild, the DSP-from-spectral-analysis decision, the vision-vs-strokes architecture, and what didn't work. 
+
+## Demo
+
+→ **[60-second walkthrough](placeholder_demo_video_url)** — a child draws, a teacher types, Lola sings.
+
+→ **[Social media post](placeholder_social_post_url)** — for sharing.
+
+## Try it yourself
+
+Web version: **[the live Space](https://huggingface.co/spaces/build-small-hackathon/lolaby)**
+
+Or to run it locally:
+
+```bash
+git clone https://huggingface.co/spaces/build-small-hackathon/lolaby
+cd lolaby
+pip install -r requirements.txt
+python app.py
+```
+
+The lyric model is fetched from the Hub on first run (~2 GB GGUF, cached after).
+
+## Dataset
+
+The lyric model was fine-tuned on **1,500 lullabies distilled from Claude Haiku 4.5** with strict anti-boilerplate gates: per-line n-gram dedup, opener dedup, theme caps, format gates, and per-example safety screening. The dataset itself, the generator (`generate_dataset.py`), and the training notebook (`train_lullaby.ipynb`) are in the [`train/`](./train/) folder. Regenerating the dataset requires an Anthropic API key; running the deployed app does not.
+
+Full details in the [model card](https://huggingface.co/build-small-hackathon/lolaby-llama-3b) and the [Field Notes blog post](placeholder_blog_url).
+
+## Repository
+
+```
+.
+├── app.py                  # Gradio entrypoint
+├── requirements.txt
+├── utils/
+│   └── safety.py               # Content-safety filter
+├── draw/                   # Drawing-related helpers
+│   ├── vision.py               # MiniCPM-V 4.6 wrapper
+│   └── strokes.py              # NumPy fallback if vision is unavailable
+├── synths/                 # Custom DSP instruments + Kokoro voice
+│   ├── guitar.py
+│   ├── piano.py
+│   ├── musicbox.py
+│   ├── harp.py
+│   ├── xylophone.py
+│   ├── ocarina.py
+│   └── voice.py
+├── train/                  # Dataset + training (build-time only; not used at runtime)
+│   ├── generate_dataset.py
+│   ├── train_lullaby.ipynb
+│   └── lullaby_dataset.jsonl
+└── tests/                  # Sanity checks for audio + LLM + voice
+```
+
+## Safety
+
+Lolaby is built for small children, so safety isn't an afterthought — it's wired through the pipeline at three points:
+
+- **At training time** — every example in the lyric model's training set was screened during dataset distillation. The model learned from already-wholesome material, not from the open web.
+- **At input time** — when a user types a *love* or *fear*, the text is screened against a curated list of terms inappropriate for a child's lullaby (death, weapons, horror, substances, self-harm). Anything matching gets a gentle redirect ("Let's keep the lullaby to gentle, cosy things…") instead of a generation.
+- **At generation time** — the same filter is shared between the runtime app and the dataset generator, so the training data and the live app can never enforce different rules.
+
+## Limitations
+
+- **English only.** The lyric model was trained on English data.
+- **First-time Space cold-start** might take some time while all models pre-warm at boot.
+- **Strange or unusual loves** may be gently generalised by the lyric model into a nearby comforting concept — that's a deliberate behaviour for a bedtime song (soft landing > literal lookup) and described in the model card.
+- **Children's drawings are interpreted by an AI** that maps rough shapes and colours onto familiar concepts — much like an adult parent guessing what a kid drew. It can miss subtle details: a stick figure becomes "a little person", a wobbly square with a triangle becomes "a house". The "Lola saw…" hint shows exactly what she understood, so you can redraw or use the What do they love? field instead.
+
+## Credits
+
+- **[Meta](https://ai.meta.com/llama/)** — Llama 3.2 3B Instruct (base model, used under the Llama 3.2 Community License).
+- **[OpenBMB](https://huggingface.co/openbmb)** — MiniCPM-V 4.6 (vision).
+- **[hexgrad/Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M)** — TTS voice.
+- **[Unsloth](https://github.com/unslothai/unsloth)** — 4-bit + LoRA training stack.
+- **[Hugging Face & Gradio](https://huggingface.co/build-small-hackathon)** — for hosting the Build Small Hackathon and creating space for small-AI projects.
+
+## License
+
+Apache 2.0 for the app code in this repo. The lyric model weights inherit the **Llama 3.2 Community License** from their base — see the [model card](https://huggingface.co/build-small-hackathon/lolaby-llama-3b) for full terms.
+
+---
+
+*Lolaby — AI-powered lullabies*

draw/strokes.py

@@ -0,0 +1,278 @@
+"""
+strokes.py — Drawing → "loves" phrase, using stroke/color analysis only.
+
+WHY THIS EXISTS
+---------------
+The drawing-input flow wants to feed something into the lullaby pipeline's
+"loves" field. A real vision-language model (MiniCPM-V) can do this richly,
+but it's slow on CPU (~4 minutes per inference on M1) and prohibitive on a
+free CPU Space. This module is the fast, no-model fallback: it reads the
+DRAWING ITSELF as structured data — colors, density, composition, energy —
+and turns that into evocative themes that feel like things the child might
+love.
+
+DESIGN PRINCIPLES
+-----------------
+- Honest about what it sees: doesn't claim to recognize objects. It reads
+  MOOD (warm/cool/bright/quiet/energetic/calm) and turns that into
+  thematic words.
+- Sub-second on CPU. Pure numpy/PIL math, zero models.
+- Varied output: same drawing twice should give slightly different phrases.
+  Built-in randomness keeps it from feeling deterministic/canned.
+- Always safe: outputs are drawn from a hand-curated wholesome vocabulary,
+  so no chance of producing unsafe themes from raw pixels.
+- Graceful with empty/sparse drawings: returns a gentle default rather than
+  crashing or producing weird output.
+
+PUBLIC INTERFACE
+----------------
+    analyze_drawing(image_pil_or_array) -> dict:
+        {
+            "loves":   str,   # phrase to feed the lullaby pipeline
+            "mood":    str,   # human-readable mood label (for UI hint)
+            "summary": str,   # one-line explanation of what was "seen"
+        }
+"""
+
+import random
+
+import numpy as np
+from PIL import Image
+
+
+# Lightweight color buckets. Each bucket carries a vocabulary of WHOLESOME
+# themes a lullaby could weave in. The exact word picked per generation is
+# randomized so the same drawing produces varied (but on-mood) lyrics.
+COLOR_THEMES = {
+    "yellow": ["the warm sun", "morning light", "honey and bees", "a glowing lantern",
+               "buttercups in the field", "a candle on the windowsill"],
+    "orange": ["a cosy fire", "autumn leaves", "a pumpkin lantern", "the sunset",
+               "ripe apricots", "a soft glowing lamp"],
+    "red":    ["red apples", "a robin in the snow", "a little red boat",
+               "a tomato in the garden", "a brave red balloon"],
+    "pink":   ["soft pink clouds", "cherry blossom", "a baby rabbit",
+               "the first roses", "watermelon slices", "a gentle flamingo"],
+    "purple": ["lavender in the breeze", "the twilight sky", "soft plums",
+               "violets in the grass", "an amethyst pebble"],
+    "blue":   ["the deep ocean", "the night sky", "raindrops on the window",
+               "a sleepy whale", "a still pond", "bluebells"],
+    "cyan":   ["the morning sky", "a gentle stream", "a glass of cool water",
+               "the misty lake", "robin-egg blue"],
+    "green":  ["the meadow grass", "tall pine trees", "a quiet forest",
+               "a curled-up turtle", "moss on stones", "lily pads"],
+    "brown":  ["a sleepy bear", "warm bread", "the trunk of the old oak",
+               "a wooden rocking horse", "fresh-turned earth", "a hedgehog"],
+    "black":  ["the gentle night", "a sleeping cat", "the soft dark",
+               "shadows that protect", "a peaceful crow"],
+    "white":  ["fresh snow", "soft clouds", "a white rabbit", "a paper crane",
+               "milk in a small cup", "a swan on the pond"],
+    "grey":   ["a soft grey rabbit", "the misty morning", "a sleeping mouse",
+               "smooth river stones", "a quiet pigeon"],
+}
+
+# Density/coverage describes how much of the canvas the child filled.
+DENSITY_WORDS = {
+    "sparse":  ["the open sky", "a wide quiet field", "a tiny world to discover"],
+    "medium":  ["a friendly little scene", "a small backyard adventure"],
+    "dense":   ["a busy garden", "a whole world packed with friends"],
+}
+
+# Stroke energy: smooth long strokes vs. many short scribbles → calm vs lively
+ENERGY_WORDS = {
+    "calm":   ["a peaceful afternoon", "everything moving slowly",
+               "a gentle, drowsy day"],
+    "lively": ["a joyful, busy day", "everything dancing and playing",
+               "a wide-awake adventure that's winding down now"],
+}
+
+
+def _empty_result():
+    """Sentinel for an empty/near-blank canvas. We return None so callers
+    can distinguish 'nothing was drawn' from 'something was drawn that I
+    interpreted'. The wrapper in app.py uses this to fall back to whatever
+    the user typed in the loves field."""
+    return None
+
+
+def _to_rgba_array(img):
+    """Accept PIL Image OR numpy array (incl. Gradio Sketchpad's dict-of-layers),
+    return an (H, W, 4) uint8 numpy array."""
+    # Gradio's ImageEditor/Sketchpad returns a dict {'background': ..., 'layers':
+    # [...], 'composite': ...}. We can't use "a or b or c" to pick the first
+    # non-None — for numpy arrays that evaluates `bool(array)` and raises
+    # "truth value is ambiguous". Test each key for `None` explicitly.
+    if isinstance(img, dict):
+        picked = None
+        for key in ("composite", "image", "background"):
+            v = img.get(key)
+            if v is not None:
+                picked = v
+                break
+        if picked is None and img.get("layers"):
+            picked = img["layers"][0]
+        img = picked
+    if img is None:
+        return None
+    if isinstance(img, np.ndarray):
+        arr = img
+    else:
+        arr = np.asarray(img.convert("RGBA"))
+    # Normalize to RGBA
+    if arr.ndim == 2:                              # grayscale
+        arr = np.stack([arr] * 3 + [np.full_like(arr, 255)], axis=-1)
+    elif arr.shape[-1] == 3:                       # RGB → add opaque alpha
+        a = np.full(arr.shape[:2] + (1,), 255, dtype=arr.dtype)
+        arr = np.concatenate([arr, a], axis=-1)
+    return arr.astype(np.uint8)
+
+
+def _classify_pixel_color(r, g, b):
+    """Map an RGB triple to a coarse color name. Handles white/grey/black
+    cleanly so background pixels don't get miscategorized as 'yellow' etc."""
+    # Brightness + saturation reasoning (cheap, no HSV conversion)
+    mx, mn = max(r, g, b), min(r, g, b)
+    brightness = mx
+    sat = mx - mn
+    if brightness > 240 and sat < 25:
+        return "white"
+    if brightness < 35:
+        return "black"
+    if sat < 25:
+        return "grey"
+    # Now we have a "real" color — bucket by which channel dominates
+    if r > 200 and g > 150 and b < 120:
+        return "yellow"
+    if r > 200 and 80 < g < 180 and b < 120:
+        return "orange"
+    if r > 180 and g < 120 and b < 120:
+        return "red"
+    if r > 200 and g < 200 and b > 180:
+        return "pink"
+    if r > 100 and b > 150 and g < 150:
+        return "purple"
+    if b > 180 and r < 150:
+        return "blue"
+    if b > 150 and g > 150 and r < 180:
+        return "cyan"
+    if g > 150 and r < 180 and b < 180:
+        return "green"
+    if 100 < r < 200 and 60 < g < 140 and b < 100:
+        return "brown"
+    # default: pick closest of the saturated buckets by dominant channel
+    if r >= g and r >= b:
+        return "red"
+    if g >= b:
+        return "green"
+    return "blue"
+
+
+def analyze_drawing(image, seed=None):
+    """Read a drawing into a 'loves'-style phrase + mood description.
+
+    image: PIL.Image, numpy array, or Gradio ImageEditor dict.
+    seed:  optional RNG seed for reproducible-ish output (mostly for tests).
+    """
+    rng = random.Random(seed)
+
+    arr = _to_rgba_array(image)
+    if arr is None or arr.size == 0:
+        return _empty_result()
+
+    h, w = arr.shape[:2]
+    rgb = arr[..., :3]
+    alpha = arr[..., 3]
+
+    # Background detection: a pixel counts as "drawn" if it's NOT near-white-opaque
+    # and (if transparent canvas) has non-zero alpha. This is intentionally
+    # generous — a child's lighter strokes still count.
+    drawn_mask = (alpha > 30) & ~(
+        (rgb[..., 0] > 240) & (rgb[..., 1] > 240) & (rgb[..., 2] > 240)
+    )
+    total_pixels = h * w
+    drawn_pixels = int(drawn_mask.sum())
+    coverage = drawn_pixels / max(1, total_pixels)
+
+    # Truly empty → gentle default
+    if coverage < 0.005:                           # less than 0.5% drawn
+        return _empty_result()
+
+    # --- Color analysis (sample for speed on large canvases) ---
+    drawn_rgb = rgb[drawn_mask]
+    if len(drawn_rgb) > 20000:
+        idx = np.linspace(0, len(drawn_rgb) - 1, 20000, dtype=int)
+        drawn_rgb = drawn_rgb[idx]
+
+    color_counts = {}
+    for px in drawn_rgb:
+        c = _classify_pixel_color(int(px[0]), int(px[1]), int(px[2]))
+        color_counts[c] = color_counts.get(c, 0) + 1
+
+    # Drop white/grey/black from the "main color" picks unless they dominate —
+    # they're often background-ish even when classified as drawn. But preserve
+    # them if they're genuinely the most-used (a deliberate black-night drawing).
+    total = sum(color_counts.values())
+    weighted = {
+        c: (n / total) for c, n in color_counts.items()
+    }
+    # Pick top 2 colors by share, but boost saturated colors slightly
+    BOOST = {"yellow": 1.2, "orange": 1.2, "red": 1.2, "pink": 1.2,
+             "purple": 1.2, "blue": 1.1, "cyan": 1.2, "green": 1.1, "brown": 1.1}
+    ranked = sorted(weighted.items(),
+                    key=lambda kv: kv[1] * BOOST.get(kv[0], 1.0),
+                    reverse=True)
+    top_colors = [c for c, _ in ranked if weighted[c] > 0.08][:2]
+    if not top_colors:
+        top_colors = [ranked[0][0]]
+
+    # --- Density bucket ---
+    if coverage < 0.05:
+        density = "sparse"
+    elif coverage < 0.25:
+        density = "medium"
+    else:
+        density = "dense"
+
+    # --- Energy: a cheap proxy is how MANY transitions between drawn and not
+    # along scan lines. Lots of transitions = many short scribbles = lively.
+    # Few transitions = long smooth strokes = calm. Subsample for speed.
+    step = max(1, h // 40)
+    transitions = 0
+    rows_sampled = 0
+    for y in range(0, h, step):
+        row = drawn_mask[y]
+        transitions += int(np.sum(row[1:] != row[:-1]))
+        rows_sampled += 1
+    avg_transitions = transitions / max(1, rows_sampled)
+    energy = "lively" if avg_transitions > 6 else "calm"
+
+    # --- Pick the loves phrase ---
+    # 1-2 color themes + maybe a density flavor + maybe an energy flavor.
+    # Randomize WHICH specific phrase per color so the same drawing varies.
+    parts = []
+    for c in top_colors:
+        if c in COLOR_THEMES:
+            parts.append(rng.choice(COLOR_THEMES[c]))
+    # 50% chance to add a density or energy color phrase
+    if rng.random() < 0.5:
+        parts.append(rng.choice(ENERGY_WORDS[energy]))
+    elif rng.random() < 0.5:
+        parts.append(rng.choice(DENSITY_WORDS[density]))
+
+    loves = ", ".join(parts) if parts else rng.choice(DENSITY_WORDS["medium"])
+
+    # --- Human-readable mood label & summary (for the UI) ---
+    mood_label_map = {
+        ("calm", "sparse"):  "quiet and dreamy",
+        ("calm", "medium"):  "calm and cosy",
+        ("calm", "dense"):   "rich and peaceful",
+        ("lively", "sparse"): "playful and light",
+        ("lively", "medium"): "happy and bright",
+        ("lively", "dense"):  "joyful and busy",
+    }
+    mood = mood_label_map.get((energy, density), "warm and gentle")
+
+    color_word = top_colors[0] if top_colors else "soft"
+    summary = (f"A {mood} drawing — lots of {color_word}, "
+               f"{'lots of small strokes' if energy == 'lively' else 'smooth gentle strokes'}.")
+
+    return {"loves": loves, "mood": mood, "summary": summary}

draw/vision.py

@@ -0,0 +1,351 @@
+"""
+vision.py — Drawing/photo → "loves" phrase via MiniCPM-V 4.6, with
+stroke-analysis fallback.
+
+DEPLOYMENT MODEL (this is the design decision that shapes everything):
+
+  - On HuggingFace ZeroGPU: the Space runs on CPU. A GPU is attached ONLY
+    inside @spaces.GPU-decorated functions, then released. This module's
+    `describe_with_vision()` is decorated, so the H200 GPU attaches just for
+    the ~few seconds of vision inference, then detaches. The lyric model
+    (llama.cpp) stays on CPU the whole time and never sees the GPU.
+
+  - On local M1 (no GPU): @spaces.GPU is a no-op (documented behavior). The
+    same function runs on CPU, slowly (~30-60s for 1.3B at 16x downsample).
+    Acceptable for local testing the pipeline end-to-end.
+
+  - If MiniCPM-V can't load at all (missing deps, oom, etc.), we fall back
+    to stroke analysis. The app never breaks — the experience just gets
+    cruder.
+
+WHY MiniCPM-V 4.6 (1.3B) AND NOT 2.6 (8B):
+  - 6x smaller → faster vision step + smaller ZeroGPU footprint per call.
+  - Quality is fine for "describe a child's drawing in 8 words" — we are
+    not doing OCR on documents.
+  - Uses standard transformers AutoModelForImageTextToText API.
+
+WHY downsample_mode="16x":
+  - 4x divides image into many tokens (finer detail, slower). 16x is faster
+    and the right precision for our task: we want themes, not pixels.
+
+PUBLIC INTERFACE:
+    vision_available() -> bool
+    describe_with_vision(image, seed=None) -> dict   # uses GPU on ZeroGPU
+    describe(image, seed=None) -> dict               # auto-picks vision or strokes
+"""
+
+import os
+import traceback
+
+# `spaces` is the HuggingFace ZeroGPU helper. It's a no-op outside HF Spaces,
+# so the decorator is safe to apply everywhere. We import it gracefully so
+# the app still runs on a fresh machine without the package installed.
+try:
+    import spaces                                                  # noqa: F401
+    _HAVE_SPACES = True
+except ImportError:
+    # Provide a no-op decorator so @spaces.GPU(...) works locally without
+    # the package — mirrors what HF's `spaces` does in non-ZeroGPU envs.
+    class _SpacesShim:
+        def GPU(self, *args, **kwargs):
+            # Support both @spaces.GPU and @spaces.GPU(duration=...)
+            if len(args) == 1 and callable(args[0]) and not kwargs:
+                return args[0]
+            def deco(fn):
+                return fn
+            return deco
+    spaces = _SpacesShim()
+    _HAVE_SPACES = False
+
+
+VISION_MODEL_ID = "openbmb/MiniCPM-V-4.6"
+
+# Tuned for "child's drawing → short loves phrase". We want concrete nouns, no
+# stylistic description ("crayon", "stick figure"), and safety baked in so the
+# vision model can't surface something dark we'd then have to filter out.
+DESCRIBE_PROMPT = (
+    "This is a young child's drawing. In 8 words or fewer, list the main "
+    "things you see as simple nouns a parent would recognise (e.g. "
+    "'a cat, the sun, a little house'). Only list wholesome, friendly things "
+    "suitable for a bedtime lullaby. Do not describe the drawing style — "
+    "just the things in it. Do not add commentary."
+)
+
+
+# Lazy globals — load the model ONCE on first call, keep it loaded. On
+# ZeroGPU the model lives in CPU memory between calls and is moved/used on
+# the GPU only inside the decorated function.
+_model = None
+_processor = None
+_load_error = None
+
+
+def _try_load():
+    """Best-effort lazy load. Returns True on success, False otherwise.
+    On failure, the reason is stashed in _load_error for diagnostics."""
+    global _model, _processor, _load_error
+    if _model is not None:
+        return True
+    if _load_error is not None:                # we already tried and failed
+        return False
+    try:
+        import torch
+        from transformers import AutoModelForImageTextToText, AutoProcessor
+        print(f"[vision] loading {VISION_MODEL_ID} (first call only)...")
+        _processor = AutoProcessor.from_pretrained(VISION_MODEL_ID,
+                                                    trust_remote_code=True)
+        # Pick a placement strategy that AVOIDS disk offload. The "auto" map
+        # on a low-RAM machine offloads parts to disk, producing the
+        # "meta device" warning AND a shape-mismatch error at inference time
+        # (weights placed in the wrong submodules). We pick explicitly:
+        #   - CUDA available → use it (ZeroGPU's H200, your dev box).
+        #   - MPS available → Apple Silicon GPU (M1/M2/M3 Macs).
+        #   - else CPU (slow but correct).
+        if torch.cuda.is_available():
+            target_device = "cuda"
+            dtype = torch.bfloat16
+        elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            target_device = "mps"
+            dtype = torch.float16   # mps doesn't love bfloat16
+        else:
+            target_device = "cpu"
+            dtype = torch.float32   # cpu can't do bfloat16 reliably
+        print(f"[vision] device={target_device} dtype={dtype}")
+        _model = AutoModelForImageTextToText.from_pretrained(
+            VISION_MODEL_ID,
+            torch_dtype=dtype,
+            trust_remote_code=True,
+            low_cpu_mem_usage=True,
+        ).to(target_device)
+        _model.eval()
+        print("[vision] loaded.")
+        return True
+    except Exception as e:
+        _load_error = f"{type(e).__name__}: {e}"
+        print(f"[vision] load failed → falling back to stroke analysis. "
+              f"reason: {_load_error}")
+        traceback.print_exc()
+        return False
+
+
+def vision_available():
+    """True iff the vision model is loaded (or can be lazily loaded).
+    Cheap to call; the actual model load is deferred to the first describe()."""
+    if _model is not None:
+        return True
+    if _load_error is not None:
+        return False
+    # We DON'T trigger a load here — that would block the UI. Just report
+    # whether transformers is importable, as a hint to the UI.
+    try:
+        import transformers  # noqa: F401
+        import torch  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+# duration=120s gives us plenty of slack on ZeroGPU (a 1.3B vision pass at
+# 16x downsample should take ~3-10s on H200, but first-call warmup can add
+# time and we never want to bail mid-inference).
+@spaces.GPU(duration=120)
+def describe_with_vision(image, seed=None):
+    """Run MiniCPM-V on the image. On ZeroGPU this is the only function that
+    holds a GPU. Returns the SAME shape as strokes.analyze_drawing()."""
+    if not _try_load():
+        # Model can't load — caller should fall back. Signal cleanly.
+        return None
+
+    import torch
+    from PIL import Image
+    import numpy as np
+
+    # ZeroGPU model: loaded on CPU at startup, moved to CUDA inside this
+    # decorated function for the duration of the call. Detect by checking if
+    # the model's current device differs from CUDA availability — if a GPU
+    # is now visible and the model is on CPU, move it.
+    global _model
+    if (torch.cuda.is_available()
+            and next(_model.parameters()).device.type == "cpu"):
+        print("[vision] ZeroGPU attached — moving model to CUDA for this call")
+        _model = _model.to("cuda")
+
+    pil = _to_pil(image)
+    if pil is None:
+        return None
+
+    # Build the chat messages in the format MiniCPM-V 4.6 expects.
+    messages = [{
+        "role": "user",
+        "content": [
+            {"type": "image", "image": pil},
+            {"type": "text", "text": DESCRIBE_PROMPT},
+        ],
+    }]
+
+    try:
+        inputs = _processor.apply_chat_template(
+            messages,
+            add_generation_prompt=True,
+            tokenize=True,
+            return_dict=True,
+            return_tensors="pt",
+            # 16x = fewer visual tokens = faster. Right precision for our task.
+            downsample_mode="16x",
+        ).to(_model.device, dtype=_model.dtype)
+
+        with torch.no_grad():
+            out_ids = _model.generate(
+                **inputs,
+                max_new_tokens=48,
+                do_sample=False,            # deterministic — keeps it concise
+            )
+        # Strip the input prompt tokens from the front before decoding
+        prompt_len = inputs["input_ids"].shape[1]
+        text = _processor.batch_decode(out_ids[:, prompt_len:],
+                                        skip_special_tokens=True)[0].strip()
+    except Exception as e:
+        print(f"[vision] inference failed: {type(e).__name__}: {e}")
+        return None
+
+    text = _clean_description(text)
+    if not text:
+        return None
+
+    return {
+        "loves":   text,
+        "mood":    "from your drawing",
+        "summary": f'Your drawing looks like: "{text}"',
+        "source":  "vision",
+    }
+
+
+def describe(image, seed=None, prefer="auto"):
+    """High-level entry: prefers vision, falls back to strokes.
+
+    prefer:
+        "auto"   — vision if available, else strokes.
+        "vision" — try vision; fall back to strokes only on failure.
+        "strokes"— always strokes (fast path, no GPU needed).
+    """
+    from draw.strokes import analyze_drawing  # local import keeps strokes optional
+
+    if prefer == "strokes" or not vision_available():
+        return _with_source(analyze_drawing(image, seed=seed), "strokes")
+
+    # Try vision, fall back silently on failure
+    result = describe_with_vision(image, seed=seed)
+    if result:
+        return result
+    return _with_source(analyze_drawing(image, seed=seed), "strokes")
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+def _to_pil(image):
+    """Accept PIL, numpy array, or Gradio ImageEditor dict; return PIL.Image
+    in RGB. Returns None for an effectively-empty canvas (so the caller can
+    fall back to a default rather than feeding noise to the model)."""
+    from PIL import Image
+    import numpy as np
+
+    if image is None:
+        return None
+    if isinstance(image, dict):
+        # ImageEditor/Sketchpad: prefer the merged composite, fall back to
+        # the image/background. Avoid `a or b or c` — for numpy arrays it
+        # raises "truth value is ambiguous". Test each key explicitly.
+        picked = None
+        for key in ("composite", "image", "background"):
+            v = image.get(key)
+            if v is not None:
+                picked = v
+                break
+        if picked is None and image.get("layers"):
+            picked = image["layers"][0]
+        image = picked
+        if image is None:
+            return None
+    if isinstance(image, np.ndarray):
+        if image.size == 0:
+            return None
+        if image.ndim == 2:
+            image = Image.fromarray(image).convert("RGB")
+        else:
+            image = Image.fromarray(image[..., :3].astype(np.uint8))
+    else:
+        image = image.convert("RGB")
+
+    # Sanity: if the canvas is almost-white, the model will return nonsense.
+    # Let the caller decide what to do — return None means "treat as empty".
+    arr = np.asarray(image)
+    if (arr > 240).all():
+        return None
+
+    # Cap size — MiniCPM-V handles big images but a 2048x2048 canvas is
+    # wasteful and slows inference. 768 on the long side is plenty for a
+    # child's drawing and matches the model's typical training resolution.
+    w, h = image.size
+    if max(w, h) > 768:
+        scale = 768 / max(w, h)
+        image = image.resize((int(w * scale), int(h * scale)), Image.LANCZOS)
+    return image
+
+
+def _clean_description(text):
+    """Strip artifacts MiniCPM-V sometimes adds, enforce length, and replace
+    drawing-technique words ('stick figure', 'sketch') with what a parent
+    would say ('a little person'). This is the WARMING layer — the prompt
+    stays literal (so the model doesn't hallucinate context that isn't on
+    the canvas), and this post-process softens any clinical jargon."""
+    import re
+    if not text:
+        return ""
+    # Drop everything after first newline / period if it's a long ramble
+    text = text.strip().strip('"').strip("'")
+    text = re.split(r"[\n\.]", text, maxsplit=1)[0].strip()
+    # Remove leading "I see " / "The image shows " etc — we want the bare list
+    text = re.sub(r"^(i see|the image shows|this drawing shows|i can see)\s+",
+                  "", text, flags=re.IGNORECASE).strip()
+
+    # Substitute drawing-technique words with warm parent-language. The vision
+    # model is technically correct ("stick figure") but emotionally cold for
+    # a lullaby. We want "a little person" instead. Order matters — match
+    # specific phrases before generic ones; consume preceding articles so we
+    # don't end up with "a a little person".
+    JARGON_FIXES = [
+        (r"\b(?:a\s+|the\s+|one\s+)?stick[\s-]?figures?\b",  "a little person"),
+        (r"\b(?:some\s+|the\s+)?stick[\s-]?people\b",        "little people"),
+        (r"\b(?:simple|crude|rough)\s+drawings?\s+of\s+",    ""),
+        (r"\b(?:a\s+)?sketch(?:es)?\s+of\s+",                ""),
+        (r"\b(?:a\s+)?(?:line|pencil|crayon|colou?red)\s+drawings?\s+of\s+", ""),
+        (r"\bdoodles?\s+of\s+",                              ""),
+        (r"\bscribbles?\s+of\s+",                            ""),
+        (r"\b(?:simple|basic|crude|rough)\s+shapes?\b",      "shapes"),
+        # If the cleaner left "a little person of dad, mom, baby" — replace
+        # the awkward "of <list of people>" with just the list of people.
+        (r"a little person of\s+", ""),
+        (r"little people of\s+",   ""),
+    ]
+    for pattern, replacement in JARGON_FIXES:
+        text = re.sub(pattern, replacement, text, flags=re.IGNORECASE)
+    # Collapse double spaces / spaces-before-commas / repeated articles
+    text = re.sub(r"\s+", " ", text).strip()
+    text = re.sub(r"\s+,", ",", text)
+    text = re.sub(r"\b(a|an|the)\s+\1\b", r"\1", text, flags=re.IGNORECASE)
+
+    # Hard length cap (the prompt asks for 8 words; clip to ~12 to be safe)
+    words = text.split()
+    if len(words) > 12:
+        text = " ".join(words[:12]).rstrip(",")
+    return text
+
+
+def _with_source(result, source):
+    """Tag a result dict with which engine produced it (for UI hints)."""
+    if result:
+        result = dict(result)
+        result["source"] = source
+    return result

requirements.txt

@@ -0,0 +1,33 @@
+# Lolaby — drawing-first edition
+# Tested with Gradio 5.x; works on Gradio 6.x with the small launch() change
+# already made in app.py.
+
+# ---- Web framework ----------------------------------------------------------
+gradio>=5.0
+
+# ---- Lyric generation (CPU, llama.cpp) --------------------------------------
+# Stays on CPU even on ZeroGPU — the vision step is the only GPU consumer.
+llama-cpp-python>=0.3.14
+
+# ---- Vision (MiniCPM-V 4.6 via HF transformers, GPU on ZeroGPU) -------------
+# Use a recent transformers — MiniCPM-V 4.6's native HF support landed in 4.45+.
+transformers>=4.45
+# Pillow for image handling on both the vision and stroke paths.
+pillow>=10
+# torchvision is needed by MiniCPM-V's image processor (torchvision backend).
+# torch is required by transformers but ZeroGPU provides its own CUDA build
+# at runtime, so we don't pin a CUDA-flavoured wheel here.
+torch>=2.4
+torchvision>=0.19
+
+# ZeroGPU runtime helper — no-op outside HF Spaces, so safe to keep listed.
+spaces
+
+# ---- Audio + numerics -------------------------------------------------------
+numpy<2          # several synths and llama-cpp interop want numpy 1.x
+scipy>=1.10
+soundfile>=0.12
+
+# ---- TTS (Kokoro, the spoken lullaby voice) ---------------------------------
+kokoro>=0.9.4
+# kokoro pulls torch transitively but we pin it explicitly above.

synths/guitar.py

@@ -0,0 +1,393 @@
+"""
+Acoustic guitar synthesizer — rebuilt from spectral analysis of two
+Freesound acoustic guitar reference recordings.
+
+Analysis findings (F#4 isolated note from ref_guitar2):
+  Spectrum (×N is harmonic of fundamental):
+    H1 (×1.0):  amp 202   the fundamental
+    H2 (×2.0):  amp  55   weaker than H1 and H3
+    H3 (×3.0):  amp 235   STRONGER than fundamental — steel string signature
+    H4 (×4.0):  amp  26
+    H5 (×5.0):  amp  23
+    H6 (×6.0):  amp  13
+    H7-H13: present out to 5kHz+ — bright, articulate
+
+  Envelope (post-attack peak):
+    Attack to peak: ~50-90ms
+    -3dB:  186ms
+    -6dB:  348ms
+    -12dB: ~700-1100ms
+
+  Strong pluck transient on attack (pick or fingernail click).
+
+The dominant-H3 character is what makes a steel-string acoustic guitar
+sound bright and "country" rather than warm and "classical". A naive
+Karplus-Strong does NOT reproduce this — it generates a monotonically
+falling harmonic series. So we layer KS (for natural string sympathetic
+behavior) with explicit boosted-H3 partials and pluck transient noise.
+
+Public interface (used by app.py):
+  GuitarSynth().sequence(events, effects=ACOUSTIC_PRESET) → np.ndarray
+  ACOUSTIC_PRESET: list of effect callables, applied in order
+
+Event format:
+  {"type": "chord", "name": "C", "time": 0.0, "duration": 3.0,
+   "direction": "down", "spread_ms": 60,
+   "volume": 0.6, "decay": 0.997, "brightness": 0.5}
+  {"type": "note", "name": "G4", "time": 0.0, "duration": 1.0,
+   "volume": 1.0, "brightness": 0.5}
+"""
+
+import numpy as np
+from scipy.signal import lfilter, butter
+
+SR = 44100
+
+NOTE_TO_SEMI = {
+    "C": 0, "C#": 1, "Db": 1, "D": 2, "D#": 3, "Eb": 3, "E": 4, "F": 5,
+    "F#": 6, "Gb": 6, "G": 7, "G#": 8, "Ab": 8, "A": 9, "A#": 10, "Bb": 10, "B": 11,
+}
+
+# Chord voicings (semitone offsets from root). Tuned for the guitar's
+# natural register — fuller than a triad to sound like a strummed shape.
+CHORD_INTERVALS = {
+    "":     [0, 7, 12, 16, 19, 24],    # major: root + 5 + oct + 3rd-up + 5-up + 2oct
+    "m":    [0, 7, 12, 15, 19, 24],    # minor: same but b3
+    "7":    [0, 7, 10, 16, 19, 22],
+    "m7":   [0, 7, 10, 15, 19, 22],
+    "maj7": [0, 7, 11, 16, 19, 23],
+    "sus2": [0, 7, 12, 14, 19, 24],
+    "sus4": [0, 7, 12, 17, 19, 24],
+}
+
+
+def parse_chord(name):
+    name = name.strip()
+    if len(name) >= 2 and name[1] in ("#", "b"):
+        root, quality = name[:2], name[2:]
+    else:
+        root, quality = name[:1], name[1:]
+    return root, quality
+
+
+def note_to_hz(name):
+    name = name.strip()
+    for i, ch in enumerate(name):
+        if ch.isdigit() or ch == "-":
+            pitch = name[:i]
+            octave = int(name[i:])
+            break
+    else:
+        pitch, octave = name, 4
+    midi = 12 * (octave + 1) + NOTE_TO_SEMI[pitch]
+    return 440.0 * 2 ** ((midi - 69) / 12)
+
+
+def chord_to_freqs(chord_name, base_octave=3):
+    """Return list of frequencies in Hz for each string in the chord voicing."""
+    root, quality = parse_chord(chord_name)
+    intervals = CHORD_INTERVALS.get(quality, CHORD_INTERVALS[""])
+    root_midi = 12 * (base_octave + 1) + NOTE_TO_SEMI[root]
+    return [440.0 * 2 ** ((root_midi + i - 69) / 12) for i in intervals]
+
+
+def add_at(track, audio, start_sec, sr=SR):
+    start = int(start_sec * sr)
+    end = start + len(audio)
+    if end > len(track):
+        track = np.pad(track, (0, end - len(track)))
+    track[start:end] += audio
+    return track
+
+
+def normalize(x, target=0.95):
+    peak = float(np.max(np.abs(x)))
+    if peak > 1e-9:
+        return x * (target / peak)
+    return x
+
+
+# ---------- effect building blocks ----------
+
+def lowpass(audio, cutoff=7500, sr=SR, order=2):
+    b, a = butter(order, cutoff / (sr / 2), btype="low")
+    return lfilter(b, a, audio).astype(np.float32)
+
+
+def highpass(audio, cutoff=80, sr=SR, order=1):
+    b, a = butter(order, cutoff / (sr / 2), btype="high")
+    return lfilter(b, a, audio).astype(np.float32)
+
+
+def gentle_compress(audio, threshold=0.7, ratio=2.5):
+    """Soft-knee compression for evening out plucks."""
+    out = audio.copy()
+    over = np.abs(out) > threshold
+    sign = np.sign(out[over])
+    excess = np.abs(out[over]) - threshold
+    out[over] = sign * (threshold + excess / ratio)
+    return out
+
+
+def body_resonance(audio, sr=SR, mix=0.18):
+    """
+    Body resonance simulation — three narrow bandpass peaks at the
+    typical acoustic guitar body resonances:
+      - Helmholtz (air): ~100 Hz
+      - Top plate:       ~200 Hz
+      - Back plate:      ~380 Hz
+    Mixed back in at low gain — gives the "boxy warm body" sound.
+    """
+    res = np.zeros_like(audio)
+    for freq, q_width, gain in [
+        (100, 60, 0.40),
+        (200, 100, 0.35),
+        (380, 150, 0.25),
+    ]:
+        low = max(20, freq - q_width)
+        high = min(sr / 2 * 0.95, freq + q_width)
+        b, a = butter(2, [low / (sr / 2), high / (sr / 2)], btype="band")
+        res += lfilter(b, a, audio).astype(np.float32) * gain
+    return audio + res * mix
+
+
+# ACOUSTIC_PRESET: pipeline applied to the final mix. Each callable takes
+# (audio,) and returns audio.
+ACOUSTIC_PRESET = [
+    lambda x: body_resonance(x, mix=0.20),
+    lambda x: highpass(x, cutoff=70),
+    lambda x: lowpass(x, cutoff=8500),
+    lambda x: gentle_compress(x, threshold=0.7, ratio=2.5),
+    lambda x: normalize(x, target=0.92),
+]
+
+
+# ---------- core string synthesis ----------
+
+def karplus_strong(freq, n_samples, sr=SR, damping=0.997, brightness=0.5):
+    """
+    Karplus-Strong plucked string. Provides the natural harmonic comb +
+    realistic decay-with-pitch behavior (high frequencies decay faster).
+    """
+    delay_len = max(2, int(round(sr / freq)))
+
+    # Pluck excitation — pre-filtered noise. Brightness controls the
+    # high-frequency content of the initial energy.
+    excitation = (np.random.rand(delay_len).astype(np.float32) * 2 - 1)
+    cutoff = 600 + brightness * 5000
+    b, a = butter(2, cutoff / (sr / 2), btype="low")
+    excitation = lfilter(b, a, excitation).astype(np.float32)
+
+    buf = excitation.copy()
+    out = np.zeros(n_samples, dtype=np.float32)
+    prev = 0.0
+    i = 0
+    for s in range(n_samples):
+        cur = buf[i]
+        out[s] = cur
+        new = damping * 0.5 * (cur + prev)
+        buf[i] = new
+        prev = cur
+        i = (i + 1) % delay_len
+    return out
+
+
+def pluck_transient(sr=SR, brightness=0.5, hardness=0.5, length_ms=8):
+    """
+    Brief filtered noise burst — the pick/fingernail attack click.
+    """
+    n = int(length_ms / 1000 * sr)
+    if n <= 0:
+        return np.zeros(0, dtype=np.float32)
+    noise = np.random.randn(n).astype(np.float32) * (0.10 + hardness * 0.10)
+    # Bandpass for "pick" character — 1.5-6 kHz
+    low = 1200 + hardness * 600
+    high = min(sr / 2 * 0.95, 4000 + brightness * 2500)
+    b, a = butter(2, [low / (sr / 2), high / (sr / 2)], btype="band")
+    click = lfilter(b, a, noise).astype(np.float32)
+    # Fast exponential decay
+    env = np.exp(-np.arange(n) / (sr * 0.0015))
+    return (click * env).astype(np.float32)
+
+
+class GuitarSynth:
+    """
+    Acoustic steel-string guitar synthesizer.
+
+    Hybrid: Karplus-Strong (sympathetic behavior + natural harmonic comb)
+    layered with explicit boosted-H3 partials (the steel-string signature)
+    and a pluck transient.
+    """
+
+    def __init__(self, sr=SR):
+        self.sr = sr
+
+    def note(self, freq, duration_s, volume=1.0, brightness=0.5):
+        """
+        Single plucked string.
+
+        brightness: 0..1. 0.5 matches the reference reasonably; bump higher
+                    for more bright country-strum feel.
+        """
+        sr = self.sr
+        # Render long enough for the full decay tail (~1.5s perceptible)
+        n = max(int(duration_s * sr), int(1.8 * sr))
+        t = np.arange(n) / sr
+
+        # Damping scales with pitch: lower notes sustain longer.
+        # Tuned so F#4 (370 Hz) hits the ~350ms -6dB measured in the reference.
+        damping = max(0.9955, 0.9992 - (freq / 18000.0))
+        ks = karplus_strong(freq, n, sr, damping=damping, brightness=brightness)
+
+        # Envelope: ~70ms attack-to-peak (the reference had peak at 70-93ms,
+        # which is the body response building up), then exponential decay
+        # with tau ≈ 0.9s (matches -6dB at ~348ms after a 60ms plateau).
+        plateau_n = int(0.06 * sr)
+        decay_tau = 0.9
+        env = np.ones(n, dtype=np.float32)
+        if plateau_n > 1:
+            env[:plateau_n] = np.linspace(0.6, 1.0, plateau_n) ** 0.8
+        decay_n = n - plateau_n
+        decay_t = np.arange(decay_n) / sr
+        env[plateau_n:] = np.exp(-decay_t / decay_tau)
+        ks = ks * env
+
+        # Explicit partials to inject the steel-string-signature H3 dominance.
+        # Reference ratios H1:H2:H3:H4:H5 ≈ 1.00 : 0.27 : 1.16 : 0.13 : 0.11.
+        # KS already provides H1 + falling tail. We add JUST enough H3 to push
+        # it slightly above the fundamental, plus a touch of H5 for sparkle.
+        h3_amp = 0.07 + brightness * 0.04
+        h5_amp = 0.02 + brightness * 0.02
+
+        h3_env_tau = decay_tau * 0.7
+        h5_env_tau = decay_tau * 0.5
+        h3_env = np.ones(n, dtype=np.float32)
+        h5_env = np.ones(n, dtype=np.float32)
+        if plateau_n > 1:
+            h3_env[:plateau_n] = np.linspace(0.6, 1.0, plateau_n) ** 0.8
+            h5_env[:plateau_n] = np.linspace(0.6, 1.0, plateau_n) ** 0.8
+        h3_env[plateau_n:] = np.exp(-decay_t / h3_env_tau)
+        h5_env[plateau_n:] = np.exp(-decay_t / h5_env_tau)
+
+        partials = h3_amp * np.sin(2 * np.pi * freq * 3 * t) * h3_env
+        if freq * 5 < sr / 2 * 0.9:
+            partials += h5_amp * np.sin(2 * np.pi * freq * 5 * t) * h5_env
+
+        # Pluck transient — adds the attack "click"
+        click = pluck_transient(sr=sr, brightness=brightness,
+                                 hardness=0.3 + brightness * 0.2, length_ms=6)
+
+        signal = ks * 0.75 + partials * 0.5
+        # Stamp the click at the front
+        click_n = len(click)
+        if click_n > 0 and click_n < n:
+            signal[:click_n] += click * 0.5
+
+        # Soft attack ramp (3ms) to prevent any DC pop
+        ramp_n = int(0.003 * sr)
+        if ramp_n > 1:
+            signal[:ramp_n] *= np.linspace(0, 1, ramp_n)
+        # Release tail
+        rel_n = int(0.05 * sr)
+        if rel_n > 1:
+            signal[-rel_n:] *= np.linspace(1, 0, rel_n)
+
+        # Final lowpass to tame any KS aliasing or harshness
+        signal = lowpass(signal, cutoff=9000, sr=sr)
+
+        # Normalize per-note for consistent loudness across pitches
+        peak = float(np.max(np.abs(signal)))
+        if peak > 1e-9:
+            signal = signal / peak * 0.85
+        return (signal * volume).astype(np.float32)
+
+    def chord(self, chord_name, duration_s, base_octave=3,
+              direction="down", spread_ms=20,
+              volume=0.7, brightness=0.5, decay=None):
+        """
+        Render a strummed chord.
+
+        spread_ms is the TOTAL time the pick takes to cross all strings
+        (not per-string). A real strum sweeps in 15-30ms; anything over
+        ~80ms starts to sound arpeggiated rather than strummed.
+
+        direction: "down" = bass-to-treble (typical down-strum)
+                   "up"   = treble-to-bass (up-strum)
+        """
+        freqs = chord_to_freqs(chord_name, base_octave=base_octave)
+        if direction == "up":
+            freqs = list(reversed(freqs))
+
+        # Total strum across all strings → per-string stagger
+        # Subtract 1 because we have N-1 gaps between N strings
+        n_strings = len(freqs)
+        if n_strings <= 1:
+            stagger = 0.0
+        else:
+            stagger = (spread_ms / 1000.0) / (n_strings - 1)
+
+        note_dur = max(duration_s, 1.5)
+        total_len = int((duration_s + stagger * n_strings + 1.5) * self.sr)
+        out = np.zeros(total_len, dtype=np.float32)
+
+        for i, freq in enumerate(freqs):
+            # Voicing: bass string slightly stronger
+            voice_vol = 1.0 if i == 0 else (0.85 if i < 3 else 0.7)
+            note_audio = self.note(freq, note_dur,
+                                    volume=volume * voice_vol,
+                                    brightness=brightness)
+            start = int(i * stagger * self.sr)
+            end = start + len(note_audio)
+            if end > len(out):
+                out = np.pad(out, (0, end - len(out)))
+            out[start:end] += note_audio
+
+        # Normalize the strummed chord
+        peak = float(np.max(np.abs(out)))
+        if peak > 1.0:
+            out = out / peak
+        return out.astype(np.float32)
+
+    def sequence(self, events, effects=None):
+        """
+        Render a list of chord/note events. Apply `effects` pipeline to the
+        final mix (in order). ACOUSTIC_PRESET is the recommended default.
+        """
+        if not events:
+            return np.zeros(int(self.sr), dtype=np.float32)
+
+        events = sorted(events, key=lambda e: e["time"])
+        end_time = max(e["time"] + max(e["duration"], 0.6) for e in events) + 2.0
+        track = np.zeros(int(end_time * self.sr) + 1, dtype=np.float32)
+
+        for ev in events:
+            typ = ev.get("type")
+            if typ == "chord":
+                # Accept the same params app.py passes today: name, time,
+                # duration, direction, spread_ms, volume, decay, brightness.
+                # `decay` is informational — actual decay is per-pitch.
+                audio = self.chord(
+                    ev["name"], ev["duration"],
+                    base_octave=ev.get("octave", ev.get("base_octave", 3)),
+                    direction=ev.get("direction", "down"),
+                    spread_ms=ev.get("spread_ms", 60),
+                    volume=ev.get("volume", 0.7),
+                    brightness=ev.get("brightness", 0.5),
+                )
+            elif typ == "note":
+                freq = note_to_hz(ev["name"])
+                audio = self.note(
+                    freq, max(ev["duration"], 1.5),
+                    volume=ev.get("volume", 1.0),
+                    brightness=ev.get("brightness", 0.5),
+                )
+            else:
+                continue
+            track = add_at(track, audio, ev["time"], sr=self.sr)
+
+        # Apply post-effects pipeline if given
+        if effects:
+            for fx in effects:
+                track = fx(track)
+
+        return track

synths/harp.py

@@ -0,0 +1,381 @@
+"""
+Harp synthesizer — based on spectral analysis of two Freesound reference clips
+(freesound_community-harp-motif2 and remembrance-harp).
+
+Analysis findings:
+  - Strong fundamental, with H2 at ~0.67× the fundamental's amplitude
+    (warm "woody" character — much more H2 than the xylophone's 1:0.03)
+  - H3 weak (~0.06×), faint H6 visible
+  - Envelope: ~70ms plateau at peak, then exponential decay
+      -6dB at  ~210ms post-peak
+      -20dB at ~770ms
+      -40dB at ~1.7s
+      Fully inaudible by ~2-3s
+  - Chord arpeggio interval (when arpeggiated): ~110-200ms between strikes
+
+Hybrid synthesis: a long-decay Karplus-Strong string for the natural harmonic
+comb and sympathetic-ringing character, layered with explicit sine partials
+for the fundamental + H2 to match the reference's warmth.
+"""
+
+import numpy as np
+from scipy.signal import lfilter, butter
+
+SR = 44100
+
+NOTE = {
+    "C": 0, "C#": 1, "Db": 1, "D": 2, "D#": 3, "Eb": 3, "E": 4, "F": 5,
+    "F#": 6, "Gb": 6, "G": 7, "G#": 8, "Ab": 8, "A": 9, "A#": 10, "Bb": 10, "B": 11,
+}
+
+CHORD_INTERVALS = {
+    "":     [0, 4, 7, 12],
+    "m":    [0, 3, 7, 12],
+    "7":    [0, 4, 7, 10],
+    "m7":   [0, 3, 7, 10],
+    "maj7": [0, 4, 7, 11],
+    "sus2": [0, 2, 7, 12],
+    "sus4": [0, 5, 7, 12],
+}
+
+
+def parse_chord(name):
+    name = name.strip()
+    if len(name) >= 2 and name[1] in ("#", "b"):
+        root, quality = name[:2], name[2:]
+    else:
+        root, quality = name[:1], name[1:]
+    return root, quality
+
+
+def note_to_hz(name):
+    name = name.strip()
+    for i, ch in enumerate(name):
+        if ch.isdigit() or ch == "-":
+            pitch = name[:i]
+            octave = int(name[i:])
+            break
+    else:
+        pitch, octave = name, 4
+    midi = 12 * (octave + 1) + NOTE[pitch]
+    return 440.0 * 2 ** ((midi - 69) / 12)
+
+
+def chord_to_freqs(chord_name, octave=3):
+    root, quality = parse_chord(chord_name)
+    intervals = CHORD_INTERVALS.get(quality, CHORD_INTERVALS[""])
+    root_midi = 12 * (octave + 1) + NOTE[root]
+    return [440.0 * 2 ** ((root_midi + i - 69) / 12) for i in intervals]
+
+
+def add_at(track, audio, start_sec):
+    start = int(start_sec * SR)
+    end = start + len(audio)
+    if end > len(track):
+        track = np.pad(track, (0, end - len(track)))
+    track[start:end] += audio
+    return track
+
+
+def simple_reverb(audio, sr, room_size=0.6, damping=0.55, wet=0.22):
+    """
+    Multi-tap delay reverb. Produces ~1.5-2s tail with diffusion.
+
+    The tail is built from 6 delayed, lowpassed, feedback-recirculated copies
+    of the input. Each tap has a slightly different delay (prime-ish ratios
+    to avoid metallic resonance) and decay factor.
+
+    Parameters:
+        room_size: 0..1 — scales tap delays (bigger = longer tail)
+        damping:   0..1 — lowpass cutoff scaling (more = darker tail)
+        wet:       0..1 — wet/dry mix (0 = dry, 1 = all reverb)
+    """
+    if wet <= 0.0:
+        return audio
+
+    n = len(audio)
+    # Tap delays in ms (prime-ratio spread, scaled by room_size)
+    base_delays_ms = [29.0, 37.0, 53.0, 67.0, 89.0, 113.0]
+    # Per-tap gain — earlier taps stronger
+    gains = [0.55, 0.48, 0.42, 0.36, 0.30, 0.24]
+
+    # Build the wet signal
+    wet_buf = np.zeros(n + int(sr * 2.0), dtype=np.float32)
+
+    # Lowpass for the diffuse tail (darker as `damping` increases)
+    cutoff = max(800.0, 5000.0 * (1.0 - damping))
+    b_lp, a_lp = butter(2, cutoff / (sr / 2), btype="low")
+    pre_lp = lfilter(b_lp, a_lp, audio).astype(np.float32)
+
+    for ms, g in zip(base_delays_ms, gains):
+        delay_samples = int(ms * sr / 1000.0 * (0.6 + room_size * 0.8))
+        end = delay_samples + n
+        if end > len(wet_buf):
+            wet_buf = np.pad(wet_buf, (0, end - len(wet_buf)))
+        wet_buf[delay_samples:end] += pre_lp * g
+
+    # Feedback recirculation — pass the wet signal through a single combed
+    # delay to build a smooth tail. Decay set by `room_size`.
+    fb_delay = int(0.071 * sr * (0.6 + room_size * 0.8))
+    fb_gain = 0.45 + room_size * 0.20    # 0.45..0.65
+    for k in range(1, 5):
+        offset = fb_delay * k
+        if offset >= len(wet_buf):
+            break
+        wet_buf[offset:] += wet_buf[:-offset] * (fb_gain ** k) * 0.5
+
+    # Trim wet to length, lowpass again to smooth
+    wet_buf = wet_buf[:n]
+    wet_buf = lfilter(b_lp, a_lp, wet_buf).astype(np.float32)
+
+    return (audio * (1.0 - wet) + wet_buf * wet).astype(np.float32)
+
+
+def _karplus_strong(freq, n_samples, sr, damping=0.9985):
+    """
+    Karplus-Strong plucked string. Integer-sample delay line.
+
+    Note on tuning: at very high pitches (above A6 or so), the integer-sample
+    delay rounding introduces a small pitch error (a few cents). We accept
+    this because (a) musical content rarely sits above A6 in lullabies, and
+    (b) the perceived "out of tune" issue in chord contexts isn't this — it's
+    overlapping ring-out from previous chords. We mitigate that by fading the
+    track between chord changes in sequence().
+
+    Damping near 1.0 = long sustain. For the harp, ~0.9985 (very slow decay).
+    """
+    delay_len = max(2, int(round(sr / freq)))
+    # Soft pre-filtered noise excitation — finger pad not pick
+    excitation = (np.random.rand(delay_len).astype(np.float32) * 2 - 1)
+    b, a = butter(2, [200 / (sr / 2), 3500 / (sr / 2)], btype="band")
+    excitation = lfilter(b, a, excitation).astype(np.float32)
+
+    buf = excitation.copy()
+    out = np.zeros(n_samples, dtype=np.float32)
+    prev = 0.0
+    i = 0
+    for s in range(n_samples):
+        cur = buf[i]
+        out[s] = cur
+        # One-pole lowpass averaging = string damping
+        new = damping * 0.5 * (cur + prev)
+        buf[i] = new
+        prev = cur
+        i = (i + 1) % delay_len
+    return out
+
+
+class HarpSynth:
+    """Concert / Celtic harp — long-sustain plucked string with warm H2."""
+
+    def __init__(self, sr=SR):
+        self.sr = sr
+
+    def note(self, freq, duration_s, volume=1.0, brightness=0.4):
+        """
+        One plucked harp string.
+
+        brightness: 0..1 — controls additive H2/H3 level and pluck attack
+                    noise. 0.4 matches the reference well.
+        """
+        sr = self.sr
+        # Render long enough for the full decay tail — at least 2.5s.
+        # Reference decays to -40dB at ~1.7s and is inaudible by ~2.5s.
+        n = max(int(duration_s * sr), int(2.5 * sr))
+        t = np.arange(n) / sr
+
+        # Damping: scaled with pitch. Low strings sustain longer (concert harp
+        # bass strings ring ~3s; high strings ~1-1.5s).
+        damping = max(0.994, 0.9991 - (freq / 8000.0))
+        ks = _karplus_strong(freq, n, sr, damping=damping)
+
+        # Reference envelope: ~70ms plateau then exponential decay with tau
+        # such that -6dB @ 210ms, -20dB @ 770ms. tau ≈ 0.33s.
+        plateau_end = 0.07
+        decay_tau = 0.33
+        env = np.ones(n, dtype=np.float32)
+        plateau_n = int(plateau_end * sr)
+        if plateau_n > 1:
+            env[:plateau_n] = np.linspace(0.85, 1.0, plateau_n)
+        decay_n = n - plateau_n
+        decay_t = np.arange(decay_n) / sr
+        env[plateau_n:] = np.exp(-decay_t / decay_tau)
+
+        ks = ks * env
+
+        # Additive partials to match reference spectrum:
+        #   fundamental:H2 ≈ 1:0.67  H3 ≈ 1:0.06
+        # KS naturally produces some H2 but typically under-weights it for
+        # a warm harp tone. Layer explicit sines with their own envelopes.
+        h1_amp = 0.45
+        h2_amp = 0.30 + brightness * 0.10   # the warm "woody" component
+        h3_amp = 0.04 + brightness * 0.025
+
+        # Partials use the same envelope curve but with slightly faster decay
+        # for higher harmonics (real strings lose high frequencies first)
+        h2_env_tau = decay_tau * 0.75
+        h3_env_tau = decay_tau * 0.55
+        h2_env = np.ones(n, dtype=np.float32)
+        h3_env = np.ones(n, dtype=np.float32)
+        if plateau_n > 1:
+            h2_env[:plateau_n] = np.linspace(0.85, 1.0, plateau_n)
+            h3_env[:plateau_n] = np.linspace(0.85, 1.0, plateau_n)
+        h2_env[plateau_n:] = np.exp(-decay_t / h2_env_tau)
+        h3_env[plateau_n:] = np.exp(-decay_t / h3_env_tau)
+
+        partials = (h1_amp * np.sin(2 * np.pi * freq * t) * env
+                    + h2_amp * np.sin(2 * np.pi * freq * 2 * t) * h2_env
+                    + (h3_amp * np.sin(2 * np.pi * freq * 3 * t) * h3_env
+                       if freq * 3 < sr / 2 * 0.9 else 0))
+
+        signal = ks * 0.55 + partials
+
+        # Soft attack ramp — no clicks
+        atk_n = int(0.004 * sr)
+        if atk_n > 1:
+            signal[:atk_n] *= np.linspace(0, 1, atk_n)
+
+        # Gentle release tail
+        rel_n = int(0.05 * sr)
+        if rel_n > 1:
+            signal[-rel_n:] *= np.linspace(1, 0, rel_n)
+
+        # Final lowpass for warm tone — kills any KS high-freq harshness
+        b_warm, a_warm = butter(2, 4000 / (sr / 2), btype="low")
+        signal = lfilter(b_warm, a_warm, signal).astype(np.float32)
+
+        # Normalize per-note for consistent loudness across pitches
+        peak = float(np.max(np.abs(signal)))
+        if peak > 1e-9:
+            signal = signal / peak * 0.85
+        return (signal * volume).astype(np.float32)
+
+    def chord(self, chord_name, duration_s, octave=3,
+              volume=0.7, brightness=0.4,
+              arpeggio_ms=130, direction="up",
+              sympathetic=True):
+        """
+        Rolled chord arpeggio — the harp signature.
+
+        arpeggio_ms: 80-180ms between successive note onsets. 130ms is dreamy.
+        sympathetic: add faint lowpassed delayed copy for ringing-strings feel.
+        """
+        freqs = chord_to_freqs(chord_name, octave=octave)
+        if direction == "down":
+            freqs = list(reversed(freqs))
+
+        stagger = arpeggio_ms / 1000.0
+        note_dur = max(duration_s, 2.5)
+        total_len = int((duration_s + stagger * len(freqs) + 3.0) * self.sr)
+        out = np.zeros(total_len, dtype=np.float32)
+
+        for i, freq in enumerate(freqs):
+            # Voicing: bass slightly stronger, top slightly softer
+            if i == 0:
+                voice_vol = 1.0
+            elif i == len(freqs) - 1:
+                voice_vol = 0.7
+            else:
+                voice_vol = 0.82
+            note_audio = self.note(freq, note_dur,
+                                    volume=volume * voice_vol,
+                                    brightness=brightness)
+            start = int(i * stagger * self.sr)
+            end = start + len(note_audio)
+            if end > len(out):
+                out = np.pad(out, (0, end - len(out)))
+            out[start:end] += note_audio
+
+        # Sympathetic resonance: delayed lowpassed copy mixed back at low gain
+        if sympathetic:
+            delay_samples = int(0.025 * self.sr)
+            b_sym, a_sym = butter(2, 1200 / (self.sr / 2), btype="low")
+            tail = lfilter(b_sym, a_sym, out).astype(np.float32)
+            shifted = np.zeros_like(out)
+            shifted[delay_samples:] = tail[:-delay_samples] * 0.18
+            out = out + shifted
+
+        # NOTE: hall-style reverb is applied in sequence() at the mix level
+        # (one pass over the whole performance) rather than per-chord, so we
+        # don't double-process.
+
+        # Normalize the rolled chord
+        peak = float(np.max(np.abs(out)))
+        if peak > 1.0:
+            out = out / peak
+        return out.astype(np.float32)
+
+    def sequence(self, events):
+        """Render chord and/or note events."""
+        if not events:
+            return np.zeros(int(self.sr), dtype=np.float32)
+
+        events = sorted(events, key=lambda e: e["time"])
+        end_time = max(e["time"] + max(e["duration"], 0.6) for e in events) + 3.0
+        track = np.zeros(int(end_time * self.sr) + 1, dtype=np.float32)
+
+        # Render each event into its own buffer, then mix with chord-aware
+        # tail damping so previous chords' rings don't beat against the new
+        # chord's harmonics (the main perceived "out of tune" sound).
+        chord_events = [e for e in events if e.get("type") == "chord"]
+        chord_starts = [e["time"] for e in chord_events]
+
+        for ev in events:
+            typ = ev.get("type")
+            if typ == "chord":
+                audio = self.chord(
+                    ev["name"], ev["duration"],
+                    octave=ev.get("octave", 3),
+                    volume=ev.get("volume", 0.7),
+                    brightness=ev.get("brightness", 0.4),
+                    arpeggio_ms=ev.get("arpeggio_ms", 130),
+                    direction=ev.get("direction", "up"),
+                    sympathetic=ev.get("sympathetic", True),
+                )
+
+                # Find the next chord boundary AFTER this one. Apply a
+                # quick exponential fade-down at that boundary on this
+                # chord's audio, so its harmonics stop ringing into the
+                # next chord. 250ms fade window — short enough to feel like
+                # natural string-damping (a harpist's palm muting), long
+                # enough not to click.
+                this_t = ev["time"]
+                next_chord_starts = [t for t in chord_starts if t > this_t + 0.1]
+                if next_chord_starts:
+                    next_t = min(next_chord_starts)
+                    # Where in `audio` does the next chord fall?
+                    relative_next = next_t - this_t       # seconds
+                    fade_start_sample = int(relative_next * self.sr)
+                    if 0 < fade_start_sample < len(audio):
+                        # Exponential fade from 1.0 → 0.18 over 250ms,
+                        # then hold at 0.18 (don't kill the tail entirely —
+                        # we want a hint of overhang for naturalness)
+                        fade_n = int(0.25 * self.sr)
+                        end_sample = min(fade_start_sample + fade_n, len(audio))
+                        n = end_sample - fade_start_sample
+                        if n > 0:
+                            curve = np.linspace(0, 1, n) ** 1.6
+                            envelope = 1.0 - curve * (1.0 - 0.18)
+                            audio[fade_start_sample:end_sample] = (
+                                audio[fade_start_sample:end_sample] * envelope
+                            )
+                        # Beyond the fade window, hold at 0.18
+                        if end_sample < len(audio):
+                            audio[end_sample:] *= 0.18
+
+            elif typ == "note":
+                freq = note_to_hz(ev["name"])
+                audio = self.note(
+                    freq, max(ev["duration"], 2.0),
+                    volume=ev.get("volume", 1.0),
+                    brightness=ev.get("brightness", 0.4),
+                )
+            else:
+                continue
+            track = add_at(track, audio, ev["time"])
+
+        # Apply hall-style reverb to the whole performance. A single pass
+        # over the mix is cheaper and more coherent than per-event reverb.
+        track = simple_reverb(track, self.sr,
+                                room_size=0.55, damping=0.50, wet=0.22)
+        return track

synths/musicbox.py

@@ -0,0 +1,320 @@
+"""
+Music box synthesizer — the quintessential lullaby instrument.
+
+A music box uses steel tines plucked by pins on a rotating cylinder.
+Acoustically, that produces a sound with very specific properties:
+
+  1) Near-pure sine fundamental (tines vibrate dominantly in their
+     fundamental mode, much more so than a struck-bar like xylophone)
+  2) A whisper of 2nd harmonic — slight metallic flavor
+  3) Brief inharmonic 'ping' at ~5-6× the fundamental — the stiffness
+     of the steel tine producing a non-integer-multiple partial that
+     fades fast (the metallic shimmer at attack)
+  4) Sharp, brief metallic attack transient — the pin-on-tine pluck.
+     Much sharper than a felt mallet, much more metallic than a piano
+     hammer. Brief HF burst (4-8 kHz) then immediate decay
+  5) Long slow decay (~2-3s for low tines, ~0.8-1.2s for high)
+  6) Distinctive 'bell' quality from the wooden box body that the tines
+     are mounted on — gives a slight reverb tail with low-mid emphasis
+  7) Sweet spot is the C5-C7 register; lower notes lose definition because
+     real music-box tines get physically large and unwieldy
+
+Reverb is baked in (small wooden-box character, not a hall). This matters:
+without the box body, the tines would sound thin and toy-like.
+
+Public interface (mirrors other synths):
+
+    from synths.musicbox import MusicBoxSynth, SR
+    synth = MusicBoxSynth()
+    synth.sequence(events) → np.ndarray @ SR
+
+Event format:
+    {"type": "chord", "name": "C", "time": 0.0, "duration": 3.0,
+     "octave": 5, "volume": 0.7, "spread_ms": 20, "direction": "up"}
+    {"type": "note", "name": "G5", "time": 0.0, "duration": 1.0,
+     "volume": 0.9}
+"""
+
+import numpy as np
+from scipy.signal import butter, lfilter
+
+SR = 44100
+
+NOTE = {
+    "C": 0, "C#": 1, "Db": 1, "D": 2, "D#": 3, "Eb": 3, "E": 4, "F": 5,
+    "F#": 6, "Gb": 6, "G": 7, "G#": 8, "Ab": 8, "A": 9, "A#": 10, "Bb": 10, "B": 11,
+}
+
+CHORD_INTERVALS = {
+    "":     [0, 4, 7, 12],
+    "m":    [0, 3, 7, 12],
+    "7":    [0, 4, 7, 10],
+    "m7":   [0, 3, 7, 10],
+    "maj7": [0, 4, 7, 11],
+    "sus2": [0, 2, 7, 12],
+    "sus4": [0, 5, 7, 12],
+}
+
+
+def parse_chord(name):
+    name = name.strip()
+    if len(name) >= 2 and name[1] in ("#", "b"):
+        root, quality = name[:2], name[2:]
+    else:
+        root, quality = name[:1], name[1:]
+    return root, quality
+
+
+def note_to_hz(name):
+    """e.g. 'A5' → 880.0"""
+    name = name.strip()
+    for i, ch in enumerate(name):
+        if ch.isdigit() or ch == "-":
+            pitch = name[:i]
+            octave = int(name[i:])
+            break
+    else:
+        pitch, octave = name, 5
+    midi = 12 * (octave + 1) + NOTE[pitch]
+    return 440.0 * 2 ** ((midi - 69) / 12)
+
+
+def chord_to_freqs(chord_name, octave=5):
+    root, quality = parse_chord(chord_name)
+    intervals = CHORD_INTERVALS.get(quality, CHORD_INTERVALS[""])
+    root_midi = 12 * (octave + 1) + NOTE[root]
+    return [440.0 * 2 ** ((root_midi + i - 69) / 12) for i in intervals]
+
+
+def add_at(track, audio, start_sec, sr=SR):
+    start = int(start_sec * sr)
+    end = start + len(audio)
+    if end > len(track):
+        track = np.pad(track, (0, end - len(track)))
+    track[start:end] += audio
+    return track
+
+
+def box_reverb(audio, sr=SR, wet=0.20):
+    """
+    Small wooden-box reverb — the resonance of the music box's housing.
+    Short (~400ms tail), dark, intimate — NOT a concert hall.
+
+    Implementation: 4 lowpassed delay taps + brief feedback. Cheap.
+    """
+    if wet <= 0.0:
+        return audio
+    n = len(audio)
+    # Tight tap spread — small box, not a room
+    delay_ms = [11.0, 19.0, 29.0, 41.0]
+    gains    = [0.55, 0.42, 0.32, 0.24]
+
+    # Pre-lowpass (the wooden box doesn't reflect high frequencies well)
+    b_lp, a_lp = butter(2, 2200 / (sr / 2), btype="low")
+    pre = lfilter(b_lp, a_lp, audio).astype(np.float32)
+
+    wet_buf = np.zeros(n + int(sr * 0.5), dtype=np.float32)
+    for ms, g in zip(delay_ms, gains):
+        d = int(ms * sr / 1000.0)
+        end = d + n
+        if end > len(wet_buf):
+            wet_buf = np.pad(wet_buf, (0, end - len(wet_buf)))
+        wet_buf[d:end] += pre * g
+
+    # Feedback for smooth decay
+    fb_delay = int(0.053 * sr)
+    for k in range(1, 3):
+        offset = fb_delay * k
+        if offset >= len(wet_buf):
+            break
+        wet_buf[offset:] += wet_buf[:-offset] * (0.35 ** k) * 0.5
+
+    wet_buf = wet_buf[:n]
+    wet_buf = lfilter(b_lp, a_lp, wet_buf).astype(np.float32)
+
+    return (audio * (1.0 - wet) + wet_buf * wet).astype(np.float32)
+
+
+def _pluck_transient(freq, sr=SR, length_ms=22):
+    """
+    The sharp metallic pin-on-tine pluck.
+
+    Two components:
+      (a) Brief broadband click in 2-8kHz (the pin striking the tine edge —
+          this is the 'tink' sound)
+      (b) A short transient sine burst at ~5× the fundamental (the inharmonic
+          stiffness partial of the tine — gives the metallic shimmer)
+
+    Decays in ~10ms. Much sharper than a felt mallet or piano hammer.
+    """
+    n = int(length_ms / 1000 * sr)
+    if n <= 0:
+        return np.zeros(0, dtype=np.float32)
+    t = np.arange(n) / sr
+
+    # Component A: HF click
+    noise = np.random.randn(n).astype(np.float32)
+    low = 2000.0
+    high = min(sr / 2 * 0.95, 8000.0)
+    b, a = butter(2, [low / (sr / 2), high / (sr / 2)], btype="band")
+    click = lfilter(b, a, noise).astype(np.float32)
+    # Very fast decay — 2ms time constant
+    click_env = np.exp(-np.arange(n) / (sr * 0.002))
+    click = click * click_env * 0.18
+
+    # Component B: brief inharmonic stiffness partial (~5× fundamental)
+    # This is what gives music box its distinctive sweet metallic ping.
+    # Higher tines have a stronger one (smaller tines are more stiff-coupled).
+    if freq < 2000:  # above this it'd alias or be inaudible
+        stiff_freq = freq * 5.4   # slightly inharmonic (not exact 5×)
+        if stiff_freq < sr / 2 * 0.9:
+            stiff_env = np.exp(-np.arange(n) / (sr * 0.008))   # 8ms decay
+            stiff_amp = 0.12 + min(0.10, freq / 8000)
+            stiff = stiff_amp * np.sin(2 * np.pi * stiff_freq * t) * stiff_env
+            click += stiff.astype(np.float32)
+
+    return click.astype(np.float32)
+
+
+class MusicBoxSynth:
+    """
+    Music box: steel tines plucked by cylinder pins.
+    Near-pure sine + faint H2 + brief inharmonic ping + long slow decay,
+    finished with a small wooden-box reverb.
+    """
+
+    def __init__(self, sr=SR):
+        self.sr = sr
+
+    def note(self, freq, duration_s, volume=1.0):
+        """
+        One plucked tine.
+
+        duration_s is mostly ignored beyond a minimum — the tine has its own
+        natural decay (~1-2.5s depending on pitch). You can't damp a music
+        box tine mid-note.
+        """
+        sr = self.sr
+        # Bass tines sustain ~2.5s; treble ~0.8s.
+        # Use pitch-scaled tau: tau = 0.6 + (110/freq) * 0.5
+        # → at 110Hz: 1.1s tau (long); at 880Hz: 0.66s tau
+        tau = max(0.30, min(1.20, 0.6 + (110.0 / freq) * 0.5))
+
+        # Render to fully capture the decay tail (5τ ≈ -40dB)
+        n = max(int(duration_s * sr), int(min(3.0, tau * 5) * sr))
+        t = np.arange(n) / sr
+
+        # Fundamental — exponential decay, no plateau (tines don't plateau
+        # like soft-mallet bars do, they start decaying immediately).
+        fund_env = np.exp(-t / tau)
+        signal = (np.sin(2 * np.pi * freq * t) * fund_env).astype(np.float32)
+
+        # Whisper of 2nd harmonic — characteristic metallic flavor
+        # H2 amp ~0.06× fundamental, decays faster (tau × 0.5)
+        if freq * 2 < sr / 2 * 0.95:
+            h2_env = np.exp(-t / (tau * 0.5))
+            signal += (0.06 * np.sin(2 * np.pi * freq * 2 * t)
+                       * h2_env).astype(np.float32)
+
+        # Tiny H3 for very low notes only — adds warmth in the bass register
+        if freq < 200 and freq * 3 < sr / 2 * 0.9:
+            h3_env = np.exp(-t / (tau * 0.4))
+            signal += (0.025 * np.sin(2 * np.pi * freq * 3 * t)
+                       * h3_env).astype(np.float32)
+
+        # Stamp the pluck transient at the front
+        pluck = _pluck_transient(freq, sr=sr)
+        if len(pluck) > 0 and len(pluck) < n:
+            signal[:len(pluck)] += pluck
+
+        # Tiny attack ramp on the sine body (no DC click)
+        ramp_n = int(0.0015 * sr)
+        if ramp_n > 1:
+            signal[:ramp_n] *= np.linspace(0, 1, ramp_n)
+
+        # Normalize per-note then scale by volume
+        peak = float(np.max(np.abs(signal)))
+        if peak > 1e-9:
+            signal = signal / peak * 0.85
+        return (signal * volume).astype(np.float32)
+
+    def chord(self, chord_name, duration_s, octave=5,
+              volume=0.7, spread_ms=20, direction="up"):
+        """
+        Render a chord. Real music boxes either pluck all tines simultaneously
+        (the cylinder pins for a chord line up) or sequentially (the cylinder
+        rotates through the notes). Both are valid.
+
+        spread_ms 0-40 = simultaneous chord; 100+ = sequential cylinder roll.
+        """
+        freqs = chord_to_freqs(chord_name, octave=octave)
+        if direction == "down":
+            freqs = list(reversed(freqs))
+
+        n_keys = len(freqs)
+        stagger = (spread_ms / 1000.0) / max(1, n_keys - 1) if n_keys > 1 else 0
+
+        note_dur = max(duration_s, 1.5)
+        total_len = int((duration_s + stagger * n_keys + 3.0) * self.sr)
+        out = np.zeros(total_len, dtype=np.float32)
+
+        for i, freq in enumerate(freqs):
+            # Voicing: top voice slightly stronger (the melody-bearing tine
+            # in a real music box is often the prominent one). Bass slightly
+            # softer because low tines can rumble.
+            if i == n_keys - 1:
+                voice_vol = 1.0
+            elif i == 0:
+                voice_vol = 0.78
+            else:
+                voice_vol = 0.85
+            note_audio = self.note(freq, note_dur, volume=volume * voice_vol)
+            start = int(i * stagger * self.sr)
+            end = start + len(note_audio)
+            if end > len(out):
+                out = np.pad(out, (0, end - len(out)))
+            out[start:end] += note_audio
+
+        peak = float(np.max(np.abs(out)))
+        if peak > 1.0:
+            out = out / peak
+        return out.astype(np.float32)
+
+    def sequence(self, events):
+        """Render mixed chord and note events. Applies the wooden-box reverb
+        once at the mix level."""
+        if not events:
+            return np.zeros(int(self.sr), dtype=np.float32)
+
+        events = sorted(events, key=lambda e: e["time"])
+        end_time = max(e["time"] + max(e["duration"], 0.6) for e in events) + 2.0
+        track = np.zeros(int(end_time * self.sr) + 1, dtype=np.float32)
+
+        for ev in events:
+            typ = ev.get("type")
+            if typ == "chord":
+                audio = self.chord(
+                    ev["name"], ev["duration"],
+                    octave=ev.get("octave", 5),
+                    volume=ev.get("volume", 0.7),
+                    spread_ms=ev.get("spread_ms", 20),
+                    direction=ev.get("direction", "up"),
+                )
+            elif typ == "note":
+                freq = note_to_hz(ev["name"])
+                audio = self.note(
+                    freq, ev["duration"],
+                    volume=ev.get("volume", 1.0),
+                )
+            else:
+                continue
+            track = add_at(track, audio, ev["time"], sr=self.sr)
+
+        # Apply the wooden-box reverb at the mix level.
+        track = box_reverb(track, self.sr, wet=0.22)
+
+        # Safety normalize so overlapping rings don't clip.
+        peak = float(np.max(np.abs(track)))
+        if peak > 0.95:
+            track = track * (0.95 / peak)
+        return track

synths/ocarina.py

@@ -0,0 +1,197 @@
+"""
+Whistle synthesizer — human-like whistling.
+
+A whistle is acoustically simple: near-sine fundamental + small 2nd harmonic,
+vibrato that fades in, soft envelope, light breath noise, smooth portamento
+between notes.
+
+Use as the MELODY layer over a rhythm instrument (guitar/piano/flute).
+
+Example:
+    from whistle import WhistleSynth
+    synth = WhistleSynth()
+    events = [
+        {"type": "note", "name": "G5", "time": 0.0,  "duration": 1.0},
+        {"type": "note", "name": "A5", "time": 1.0,  "duration": 0.5},
+        {"type": "note", "name": "G5", "time": 1.5,  "duration": 1.5},
+    ]
+    audio = synth.sequence(events)
+"""
+
+import numpy as np
+from scipy.signal import butter, lfilter
+
+SR = 44100
+
+NOTE = {
+    "C": 0, "C#": 1, "Db": 1, "D": 2, "D#": 3, "Eb": 3, "E": 4, "F": 5,
+    "F#": 6, "Gb": 6, "G": 7, "G#": 8, "Ab": 8, "A": 9, "A#": 10, "Bb": 10, "B": 11,
+}
+
+
+def note_to_hz(name):
+    """e.g. 'A4' → 440.0"""
+    name = name.strip()
+    # Find where the digit starts
+    for i, ch in enumerate(name):
+        if ch.isdigit() or ch == "-":
+            pitch = name[:i]
+            octave = int(name[i:])
+            break
+    else:
+        pitch, octave = name, 4
+    midi = 12 * (octave + 1) + NOTE[pitch]
+    return 440.0 * 2 ** ((midi - 69) / 12)
+
+
+def add_at(track, audio, start_sec):
+    start = int(start_sec * SR)
+    end = start + len(audio)
+    if end > len(track):
+        track = np.pad(track, (0, end - len(track)))
+    track[start:end] += audio
+    return track
+
+
+class WhistleSynth:
+    """Synthesizes a melodic whistle from note events."""
+
+    def __init__(self, sr=SR):
+        self.sr = sr
+
+    def note(self, freq, duration_s,
+             vibrato_hz=4.8, vibrato_cents=32,
+             attack_ms=120, release_ms=400,
+             breath_level=0.018,
+             prev_freq=None, glide_ms=80,
+             volume=1.0):
+        """One whistled note."""
+        sr = self.sr
+        n = int(duration_s * sr)
+        if n <= 0:
+            return np.zeros(0, dtype=np.float32)
+        t = np.arange(n) / sr
+
+        # Pitch curve with optional glide from previous note
+        if prev_freq is not None and glide_ms > 0:
+            glide_n = min(int(glide_ms / 1000 * sr), n // 3)
+            freq_curve = np.full(n, freq, dtype=np.float32)
+            if glide_n > 1:
+                freq_curve[:glide_n] = np.linspace(prev_freq, freq, glide_n)
+        else:
+            freq_curve = np.full(n, freq, dtype=np.float32)
+
+        # Vibrato fades in (whistlers don't start with wobble)
+        vibrato_env = np.minimum((t - 0.2) / 0.3, 1.0).clip(0, 1)
+        depth_hz = freq_curve * (2 ** (vibrato_cents / 1200) - 1)
+        vibrato = depth_hz * vibrato_env * np.sin(2 * np.pi * vibrato_hz * t)
+        inst_freq = freq_curve + vibrato
+
+        # Phase from instantaneous frequency
+        phase = 2 * np.pi * np.cumsum(inst_freq) / sr
+
+        # Tone: fundamental + soft 2nd harmonic
+        tone = np.sin(phase) + 0.06 * np.sin(2 * phase)
+
+        # Breath: bandpassed noise around the fundamental
+        noise = np.random.randn(n).astype(np.float32)
+        f_center = float(np.mean(freq_curve))
+        low = max(80.0, f_center * 0.8)
+        high = min(sr / 2 * 0.95, f_center * 1.6)
+        b, a = butter(2, [low / (sr / 2), high / (sr / 2)], btype="band")
+        breath = lfilter(b, a, noise).astype(np.float32) * breath_level
+
+        out = (tone + breath).astype(np.float32)
+
+        # Envelope
+        env = np.ones(n, dtype=np.float32)
+        atk_n = min(int(attack_ms / 1000 * sr), n // 3)
+        rel_n = min(int(release_ms / 1000 * sr), n // 2)
+        if atk_n > 1:
+            env[:atk_n] = np.linspace(0, 1, atk_n) ** 1.5
+        if rel_n > 1:
+            env[-rel_n:] = np.linspace(1, 0, rel_n) ** 1.5
+
+        return (out * env * volume).astype(np.float32)
+
+    def _explode_chord(self, ev):
+        """
+        Break a chord event into a slow broken-chord pattern of note events.
+
+        Ocarina is monophonic, so a rhythm-role chord is rendered as a slow
+        ascending arpeggio that takes up the chord duration.
+        """
+        name = ev["name"]
+        # Parse chord
+        if len(name) >= 2 and name[1] in ("#", "b"):
+            root, quality = name[:2], name[2:]
+        else:
+            root, quality = name[:1], name[1:]
+        is_minor = "m" in quality and "maj" not in quality
+        intervals = [0, (3 if is_minor else 4), 7]   # root, third, fifth
+
+        octave = ev.get("octave", 5)
+        root_midi = 12 * (octave + 1) + NOTE[root]
+        names = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+
+        duration = ev["duration"]
+        t0 = ev["time"]
+        vol = ev.get("volume", 0.7)
+        # Three notes per chord, spread across most of the chord duration
+        note_dur = duration / 2.5
+        sub_events = []
+        for i, semi in enumerate(intervals):
+            midi = root_midi + semi
+            o = midi // 12 - 1
+            pitch_name = names[midi % 12]
+            sub_events.append({
+                "type": "note",
+                "name": f"{pitch_name}{o}",
+                "time": t0 + i * (duration / 3.5),
+                "duration": note_dur,
+                "volume": vol * (0.85 if i > 0 else 1.0),
+            })
+        return sub_events
+
+    def sequence(self, events):
+        """
+        Render note and chord events. Chords become slow broken-chord
+        arpeggios (ocarina is monophonic).
+        """
+        if not events:
+            return np.zeros(int(self.sr), dtype=np.float32)
+
+        # Expand chord events into note events
+        expanded = []
+        for ev in events:
+            if ev.get("type") == "chord":
+                expanded.extend(self._explode_chord(ev))
+            elif ev.get("type", "note") == "note":
+                expanded.append(ev)
+
+        events = sorted(expanded, key=lambda e: e["time"])
+        end_time = max(e["time"] + e["duration"] for e in events) + 0.5
+        track = np.zeros(int(end_time * self.sr) + 1, dtype=np.float32)
+
+        prev_freq = None
+        prev_end = -10.0
+
+        for ev in events:
+            freq = note_to_hz(ev["name"])
+            t = float(ev["time"])
+            dur = float(ev["duration"])
+            vol = float(ev.get("volume", 1.0))
+
+            # Use glide only if previous note ended very recently
+            glide_freq = prev_freq if (t - prev_end) < 0.25 else None
+
+            note_audio = self.note(
+                freq, dur,
+                prev_freq=glide_freq,
+                volume=vol,
+            )
+            track = add_at(track, note_audio, t)
+            prev_freq = freq
+            prev_end = t + dur
+
+        return track

synths/piano.py

@@ -0,0 +1,234 @@
+"""
+Piano synthesizer — soft felt-piano lullaby tone.
+
+Uses additive synthesis with a small handful of inharmonic partials, each
+with its own decay envelope (higher partials decay faster — that's what
+makes a piano sound like a piano vs an organ). A short stiff-attack
+transient gives the hammer strike; a long sustain gives the body.
+
+The "felt-piano" sound (a piano with felt strips between hammer and string)
+is the soft, intimate, lullaby-friendly variant — less attack, more body,
+fewer harmonics.
+"""
+
+import numpy as np
+from scipy.signal import lfilter, butter
+
+SR = 44100
+
+NOTE = {
+    "C": 0, "C#": 1, "Db": 1, "D": 2, "D#": 3, "Eb": 3, "E": 4, "F": 5,
+    "F#": 6, "Gb": 6, "G": 7, "G#": 8, "Ab": 8, "A": 9, "A#": 10, "Bb": 10, "B": 11,
+}
+
+# Chord voicings: (note offsets in semitones from root) at the given octave
+CHORD_INTERVALS = {
+    "": [0, 4, 7],           # major
+    "m": [0, 3, 7],          # minor
+    "7": [0, 4, 7, 10],      # dom 7
+    "m7": [0, 3, 7, 10],
+    "maj7": [0, 4, 7, 11],
+    "sus2": [0, 2, 7],
+    "sus4": [0, 5, 7],
+}
+
+
+def parse_chord(name):
+    """'Am' → ('A', 'm'). 'C' → ('C', ''). 'Bbm7' → ('Bb', 'm7')."""
+    name = name.strip()
+    # Match 1-2 char root, rest is quality
+    if len(name) >= 2 and name[1] in ("#", "b"):
+        root, quality = name[:2], name[2:]
+    else:
+        root, quality = name[:1], name[1:]
+    return root, quality
+
+
+def note_to_hz(name):
+    """e.g. 'A4' → 440.0"""
+    name = name.strip()
+    for i, ch in enumerate(name):
+        if ch.isdigit() or ch == "-":
+            pitch = name[:i]
+            octave = int(name[i:])
+            break
+    else:
+        pitch, octave = name, 4
+    midi = 12 * (octave + 1) + NOTE[pitch]
+    return 440.0 * 2 ** ((midi - 69) / 12)
+
+
+def chord_to_freqs(chord_name, octave=4):
+    """Return list of (frequency, relative_volume) for each note in the chord."""
+    root, quality = parse_chord(chord_name)
+    intervals = CHORD_INTERVALS.get(quality, CHORD_INTERVALS[""])
+    root_midi = 12 * (octave + 1) + NOTE[root]
+
+    notes = []
+    for i, interval in enumerate(intervals):
+        midi = root_midi + interval
+        hz = 440.0 * 2 ** ((midi - 69) / 12)
+        # Soften higher voices a touch — top of the chord shouldn't dominate
+        vol = 1.0 if i == 0 else (0.7 if i < 3 else 0.55)
+        notes.append((hz, vol))
+    return notes
+
+
+def add_at(track, audio, start_sec):
+    start = int(start_sec * SR)
+    end = start + len(audio)
+    if end > len(track):
+        track = np.pad(track, (0, end - len(track)))
+    track[start:end] += audio
+    return track
+
+
+class PianoSynth:
+    """Soft felt-piano synthesizer using additive synthesis."""
+
+    def __init__(self, sr=SR):
+        self.sr = sr
+
+    def note(self, freq, duration_s, volume=1.0, brightness=0.5):
+        """
+        One piano note via additive synthesis.
+
+        brightness: 0..1 — controls how much energy is in the upper partials.
+                    0.3 = warm/felt, 0.7 = bright/grand. Lullabies want ~0.4.
+        """
+        sr = self.sr
+        n = int(duration_s * sr)
+        if n <= 0:
+            return np.zeros(0, dtype=np.float32)
+        t = np.arange(n) / sr
+
+        # Partial amplitudes — first 6 harmonics with falloff
+        # Brightness shifts the energy curve
+        base_amps = np.array([1.0, 0.55, 0.35, 0.22, 0.14, 0.08], dtype=np.float32)
+        # Apply brightness as a tilt — more brightness = less rolloff on highs
+        amps = base_amps * (1.0 + brightness * np.arange(len(base_amps)) * 0.1)
+        amps[0] = 1.0  # keep fundamental at unity
+
+        # Piano partials are slightly inharmonic (stiffness of real strings).
+        # The inharmonicity coefficient grows roughly as n² but is small for
+        # the low-mid range — ~0.0004 for a real piano.
+        B = 0.0004
+
+        signal = np.zeros(n, dtype=np.float32)
+        for k in range(len(amps)):
+            partial = k + 1
+            # Inharmonic frequency
+            partial_freq = freq * partial * np.sqrt(1 + B * partial ** 2)
+            if partial_freq > sr / 2 * 0.95:
+                break
+
+            # Each partial has its own decay — higher partials die faster.
+            # Felt piano: fundamental rings ~4-6s, partial 6 dies in <1s.
+            decay_time = duration_s * (1.0 - 0.12 * k)
+            decay = np.exp(-t / max(decay_time, 0.2))
+
+            # Slight pitch detune per partial (real pianos have multiple strings
+            # per note with tiny detune that creates the chorus shimmer)
+            detune = 1.0 + (np.random.randn() * 0.0005 if k == 0 else 0)
+            phase = 2 * np.pi * partial_freq * detune * t
+
+            signal += amps[k] * decay * np.sin(phase)
+
+        # Hammer strike: very short noise burst at the start, lowpassed.
+        # This is what makes it sound percussive instead of bowed.
+        attack_n = min(int(0.012 * sr), n)  # 12ms
+        strike = np.random.randn(attack_n).astype(np.float32) * 0.15
+        # Lowpass the strike so it's a thud, not a click
+        b_lp, a_lp = butter(2, 2500 / (sr / 2), btype="low")
+        strike = lfilter(b_lp, a_lp, strike).astype(np.float32)
+        strike_env = np.exp(-np.arange(attack_n) / (sr * 0.005))
+        signal[:attack_n] += (strike * strike_env).astype(np.float32)
+
+        # Soft attack envelope on the body (no clicks)
+        atk_n = min(int(0.008 * sr), n)
+        if atk_n > 1:
+            signal[:atk_n] *= np.linspace(0, 1, atk_n)
+
+        # Soft release to avoid clipping silence at end
+        rel_n = min(int(0.08 * sr), n // 2)
+        if rel_n > 1:
+            signal[-rel_n:] *= np.linspace(1, 0, rel_n)
+
+        # Gentle lowpass for "felt" character
+        b_warm, a_warm = butter(1, 6000 / (sr / 2), btype="low")
+        signal = lfilter(b_warm, a_warm, signal).astype(np.float32)
+
+        # Normalize per-note then scale by volume
+        peak = float(np.max(np.abs(signal)))
+        if peak > 1e-9:
+            signal = signal / peak * 0.85
+        return signal * volume
+
+    def chord(self, chord_name, duration_s, time, octave=4,
+              direction="down", spread_ms=20, volume=0.7, brightness=0.4):
+        """
+        Render a chord as multiple piano notes with a tiny stagger.
+
+        For lullaby use, spread_ms=20-40 gives a gentle "rolled" feel like
+        a pianist landing slightly arpeggiated.
+        """
+        notes = chord_to_freqs(chord_name, octave=octave)
+        if direction == "up":
+            notes = list(reversed(notes))
+
+        # Time-stagger via the spread
+        stagger = spread_ms / 1000.0
+        chord_audio = np.zeros(int((duration_s + stagger * len(notes) + 0.5) * self.sr),
+                               dtype=np.float32)
+
+        for i, (freq, rel_vol) in enumerate(notes):
+            note_audio = self.note(freq, duration_s, volume=volume * rel_vol,
+                                    brightness=brightness)
+            start = int(i * stagger * self.sr)
+            end = start + len(note_audio)
+            if end > len(chord_audio):
+                chord_audio = np.pad(chord_audio, (0, end - len(chord_audio)))
+            chord_audio[start:end] += note_audio
+        return chord_audio
+
+    def sequence(self, events):
+        """
+        Render a sequence of chord and/or note events.
+
+        chord event: {"type": "chord", "name": "Am", "time": 0.0, "duration": 3.0, ...}
+        note event:  {"type": "note", "name": "A4", "time": 0.0, "duration": 1.0, ...}
+        """
+        if not events:
+            return np.zeros(int(self.sr), dtype=np.float32)
+
+        events = sorted(events, key=lambda e: e["time"])
+        end_time = max(e["time"] + e["duration"] for e in events) + 2.0
+        track = np.zeros(int(end_time * self.sr) + 1, dtype=np.float32)
+
+        for ev in events:
+            typ = ev.get("type")
+            if typ == "chord":
+                audio = self.chord(
+                    ev["name"],
+                    ev["duration"],
+                    ev["time"],
+                    octave=ev.get("octave", 4),
+                    direction=ev.get("direction", "down"),
+                    spread_ms=ev.get("spread_ms", 25),
+                    volume=ev.get("volume", 0.7),
+                    brightness=ev.get("brightness", 0.4),
+                )
+            elif typ == "note":
+                freq = note_to_hz(ev["name"])
+                # Piano notes ring out — extend duration for natural decay tail
+                audio = self.note(
+                    freq,
+                    ev["duration"] + 1.0,
+                    volume=ev.get("volume", 0.85),
+                    brightness=ev.get("brightness", 0.4),
+                )
+            else:
+                continue
+            track = add_at(track, audio, ev["time"])
+
+        return track

synths/voice.py

@@ -0,0 +1,107 @@
+"""
+Voice synthesis for the lullaby app — Kokoro TTS, soft preset.
+
+Reads the lyrics gently, slowly, with natural breaths between lines.
+No singing, no pitch manipulation — just a warm reading voice over music.
+"""
+
+import numpy as np
+
+SR_TARGET = 44100
+
+
+# We always use the soft voice — chosen for lullaby use.
+VOICE_DEFAULT = "af_nicole"
+
+
+_pipeline = None
+_kokoro_sr = 24000
+
+
+def _load_kokoro():
+    global _pipeline
+    if _pipeline is not None:
+        return True
+    try:
+        from kokoro import KPipeline
+        print("Loading Kokoro (first run downloads ~80MB)...")
+        _pipeline = KPipeline(lang_code='a', repo_id='hexgrad/Kokoro-82M')
+        print("Kokoro loaded.")
+        return True
+    except Exception as e:
+        print(f"Kokoro unavailable: {e}")
+        return False
+
+
+def _resample(x, sr_from, sr_to):
+    if sr_from == sr_to:
+        return x
+    n_out = int(len(x) * sr_to / sr_from)
+    return np.interp(
+        np.linspace(0, len(x) - 1, n_out),
+        np.arange(len(x)),
+        x,
+    ).astype(np.float32)
+
+
+def _silence(seconds):
+    return np.zeros(int(seconds * SR_TARGET), dtype=np.float32)
+
+
+def _gentle_vocal_eq(audio):
+    """Soften vocal tone — gentle low-pass + mild high-pass."""
+    from scipy.signal import butter, lfilter
+    b_lp, a_lp = butter(2, 5500 / (SR_TARGET / 2), btype="low")
+    b_hp, a_hp = butter(1, 110 / (SR_TARGET / 2), btype="high")
+    out = lfilter(b_lp, a_lp, audio)
+    out = lfilter(b_hp, a_hp, out)
+    return out.astype(np.float32)
+
+
+def speak_lyrics(lyrics, target_seconds=None, speed=0.85):
+    """
+    Render lyrics as gentle spoken voice. Returns mono float32 at SR_TARGET.
+
+    speed=0.85 → slightly slower than normal, bedtime pacing.
+    target_seconds (if given) → pad with intro silence so voice ends near track end.
+    """
+    if not _load_kokoro():
+        print("WARNING: TTS unavailable, returning silent vocal track")
+        return _silence(target_seconds or 1.0)
+
+    try:
+        chunks = []
+        generator = _pipeline(
+            lyrics,
+            voice=VOICE_DEFAULT,
+            speed=speed,
+            split_pattern=r'\n+',
+        )
+        for _, _, audio in generator:
+            audio_np = np.asarray(audio, dtype=np.float32)
+            if len(audio_np) == 0:
+                continue
+            chunks.append(audio_np)
+            # 350ms breath between phrases
+            chunks.append(np.zeros(int(0.35 * _kokoro_sr), dtype=np.float32))
+        if not chunks:
+            return _silence(target_seconds or 1.0)
+        audio = np.concatenate(chunks)
+        audio = _resample(audio, _kokoro_sr, SR_TARGET)
+        audio = _gentle_vocal_eq(audio)
+
+        # Pad with intro silence if requested
+        if target_seconds is not None:
+            target_n = int(target_seconds * SR_TARGET)
+            if len(audio) < target_n:
+                intro = min(target_n - len(audio), 4 * SR_TARGET)
+                audio = np.concatenate([_silence(intro / SR_TARGET), audio])
+        return audio
+    except Exception as e:
+        print(f"Kokoro generation error: {e}")
+        return _silence(target_seconds or 1.0)
+
+
+# Back-compat alias for code that imports the old name.
+def synthesize_singing(lyrics, target_seconds=20.0, voice_style="soft", **kwargs):
+    return speak_lyrics(lyrics, target_seconds=target_seconds)

synths/xylophone.py

@@ -0,0 +1,298 @@
+"""
+Xylophone synthesizer — based on spectral analysis of a real soft-mallet
+metallophone/xylophone loop reference.
+
+Analysis of the reference (van_wiese xylophone loop, 125 BPM):
+  - Fundamental at 463 Hz (A#4) with 2nd harmonic at 931 Hz
+  - Amplitude ratio fundamental:2nd ≈ 32:1 (essentially a pure sine + whisper of H2)
+  - Decay to -6dB in 86ms
+  - Decay to -20dB in ~300ms
+  - No prominent inharmonic partials (cleaner than a true wooden xylophone)
+  - Bright, near-pure tone — closer to a tuned soft-mallet metallophone
+
+This synth models that: an almost-sine fundamental, a faint 2nd harmonic,
+a tiny inharmonic shimmer for "real wood/metal" character, a brief filtered
+strike transient, and a fast exponential decay.
+
+Discrete hits, no tremolo, no roll — single mallet strikes like the reference.
+For chord roles, we play a fast arpeggio of single hits instead of a tremolo.
+"""
+
+import numpy as np
+from scipy.signal import lfilter, butter
+
+SR = 44100
+
+NOTE = {
+    "C": 0, "C#": 1, "Db": 1, "D": 2, "D#": 3, "Eb": 3, "E": 4, "F": 5,
+    "F#": 6, "Gb": 6, "G": 7, "G#": 8, "Ab": 8, "A": 9, "A#": 10, "Bb": 10, "B": 11,
+}
+
+CHORD_INTERVALS = {
+    "":     [0, 4, 7],
+    "m":    [0, 3, 7],
+    "7":    [0, 4, 7, 10],
+    "m7":   [0, 3, 7, 10],
+    "maj7": [0, 4, 7, 11],
+    "sus2": [0, 2, 7],
+    "sus4": [0, 5, 7],
+}
+
+
+def parse_chord(name):
+    name = name.strip()
+    if len(name) >= 2 and name[1] in ("#", "b"):
+        root, quality = name[:2], name[2:]
+    else:
+        root, quality = name[:1], name[1:]
+    return root, quality
+
+
+def note_to_hz(name):
+    """'A5' → 880.0"""
+    name = name.strip()
+    for i, ch in enumerate(name):
+        if ch.isdigit() or ch == "-":
+            pitch = name[:i]
+            octave = int(name[i:])
+            break
+    else:
+        pitch, octave = name, 5
+    midi = 12 * (octave + 1) + NOTE[pitch]
+    return 440.0 * 2 ** ((midi - 69) / 12)
+
+
+def chord_to_freqs(chord_name, octave=4):
+    root, quality = parse_chord(chord_name)
+    intervals = CHORD_INTERVALS.get(quality, CHORD_INTERVALS[""])
+    root_midi = 12 * (octave + 1) + NOTE[root]
+    return [440.0 * 2 ** ((root_midi + i - 69) / 12) for i in intervals]
+
+
+def add_at(track, audio, start_sec):
+    start = int(start_sec * SR)
+    end = start + len(audio)
+    if end > len(track):
+        track = np.pad(track, (0, end - len(track)))
+    track[start:end] += audio
+    return track
+
+
+def simple_reverb(audio, sr, room_size=0.5, damping=0.55, wet=0.30):
+    """
+    Multi-tap delay reverb. Adds ~1.5s tail with diffusion.
+
+    For xylophone we want more wet than the harp (xylo strikes are short
+    and dry sounds toy-like). 6 lowpassed delayed taps + a recirculating
+    feedback delay build a smooth tail without metallic resonance.
+
+    Parameters:
+        room_size: 0..1 — scales tap delays (bigger = longer tail)
+        damping:   0..1 — lowpass cutoff scaling (more = darker tail)
+        wet:       0..1 — wet/dry mix
+    """
+    if wet <= 0.0:
+        return audio
+
+    n = len(audio)
+    base_delays_ms = [29.0, 37.0, 53.0, 67.0, 89.0, 113.0]
+    gains = [0.55, 0.48, 0.42, 0.36, 0.30, 0.24]
+
+    wet_buf = np.zeros(n + int(sr * 2.0), dtype=np.float32)
+
+    cutoff = max(800.0, 5000.0 * (1.0 - damping))
+    b_lp, a_lp = butter(2, cutoff / (sr / 2), btype="low")
+    pre_lp = lfilter(b_lp, a_lp, audio).astype(np.float32)
+
+    for ms, g in zip(base_delays_ms, gains):
+        delay_samples = int(ms * sr / 1000.0 * (0.6 + room_size * 0.8))
+        end = delay_samples + n
+        if end > len(wet_buf):
+            wet_buf = np.pad(wet_buf, (0, end - len(wet_buf)))
+        wet_buf[delay_samples:end] += pre_lp * g
+
+    fb_delay = int(0.071 * sr * (0.6 + room_size * 0.8))
+    fb_gain = 0.45 + room_size * 0.20
+    for k in range(1, 5):
+        offset = fb_delay * k
+        if offset >= len(wet_buf):
+            break
+        wet_buf[offset:] += wet_buf[:-offset] * (fb_gain ** k) * 0.5
+
+    wet_buf = wet_buf[:n]
+    wet_buf = lfilter(b_lp, a_lp, wet_buf).astype(np.float32)
+
+    return (audio * (1.0 - wet) + wet_buf * wet).astype(np.float32)
+
+
+class XylophoneSynth:
+    """
+    Soft-mallet metallophone/xylophone modeled on a real reference loop.
+
+    Characteristics:
+      - Near-pure sine fundamental
+      - Whisper of 2nd harmonic (~1/30 the amplitude of fundamental)
+      - Tiny inharmonic flavor for body
+      - Fast exponential decay (~85ms to -6dB, ~300ms to -20dB)
+      - Brief click-like strike transient
+    """
+
+    def __init__(self, sr=SR):
+        self.sr = sr
+
+    def strike(self, freq, volume=1.0, brightness=0.5):
+        """
+        One mallet strike.
+
+        Models the reference envelope: brief attack peak, ~100ms near-peak
+        plateau (bar body sustain), then slow exponential decay over ~600ms.
+        Full ring-out by ~800ms.
+
+        brightness: 0..1 — affects strike click intensity and H2 level.
+                    0.5 matches the reference well.
+        """
+        sr = self.sr
+        # 900ms render — long enough for the full decay tail
+        n = int(0.9 * sr)
+        t = np.arange(n) / sr
+
+        # Reference fundamental envelope: stays near-peak until ~140ms, then
+        # decays to ~0.25 by 300ms, ~0.10 by 500ms. That's a slow exponential
+        # with tau ≈ 220ms, but with a brief plateau at the start.
+        #
+        # Model: attack ramp → short plateau → exponential decay
+        plateau_end = 0.12      # 120ms plateau
+        decay_tau = 0.22        # slow decay constant
+
+        fund_env = np.ones(n, dtype=np.float32)
+        # Plateau phase: gentle taper from 1.0 to 0.95
+        plateau_n = int(plateau_end * sr)
+        fund_env[:plateau_n] = np.linspace(1.0, 0.95, plateau_n)
+        # Decay phase: exponential from 0.95 down
+        decay_n = n - plateau_n
+        decay_t = np.arange(decay_n) / sr
+        fund_env[plateau_n:] = 0.95 * np.exp(-decay_t / decay_tau)
+
+        # H2 — barely audible, dies faster than fundamental (no plateau)
+        h2_amp = 0.04 + brightness * 0.025
+        tau_h2 = 0.090
+        h2_env = np.exp(-t / tau_h2)
+
+        signal = (np.sin(2 * np.pi * freq * t) * fund_env
+                  + h2_amp * np.sin(2 * np.pi * freq * 2 * t) * h2_env)
+
+        # Faint inharmonic shimmer at attack only — gives "real bar" texture
+        partial_3_freq = freq * 4.2
+        if partial_3_freq < sr / 2 * 0.9:
+            partial_3_env = np.exp(-t / 0.025)
+            partial_3_amp = 0.04 * brightness
+            signal += partial_3_amp * np.sin(2 * np.pi * partial_3_freq * t) * partial_3_env
+
+        # Strike transient: brief filtered noise burst.
+        attack_n = int(0.006 * sr)  # 6ms
+        if attack_n > 0:
+            noise = np.random.randn(attack_n).astype(np.float32) * 0.10
+            b, a = butter(2,
+                          [1500 / (sr / 2), min(0.95, 4500 / (sr / 2))],
+                          btype="band")
+            click = lfilter(b, a, noise).astype(np.float32)
+            click_env = np.exp(-np.arange(attack_n) / (sr * 0.002))
+            click = (click * click_env * (0.5 + brightness * 0.4)).astype(np.float32)
+            signal[:attack_n] += click
+
+        # Tiny attack ramp on the body (no DC pop)
+        ramp_n = int(0.001 * sr)
+        if ramp_n > 1:
+            signal[:ramp_n] *= np.linspace(0, 1, ramp_n)
+
+        # Normalize per-strike to a known peak, then scale by volume
+        peak = float(np.max(np.abs(signal)))
+        if peak > 1e-9:
+            signal = signal / peak * 0.80
+
+        return (signal * volume).astype(np.float32)
+
+    def chord(self, chord_name, duration_s, octave=4,
+              volume=0.7, brightness=0.5,
+              arpeggio_ms=60, direction="up"):
+        """
+        Render a chord as a quick arpeggio of individual strikes (not a roll).
+
+        Real mallet players play chords as fast arpeggios from low to high
+        (or high to low). arpeggio_ms is the delay between strikes. 40-80ms
+        feels right for lullaby pacing.
+
+        The 'duration_s' is the chord's total time-slot, but each strike
+        decays on its own ~500ms timeline regardless.
+        """
+        freqs = chord_to_freqs(chord_name, octave=octave)
+        if direction == "down":
+            freqs = list(reversed(freqs))
+
+        stagger = arpeggio_ms / 1000.0
+        total_len = int((duration_s + 0.6) * self.sr)
+        out = np.zeros(total_len, dtype=np.float32)
+
+        for i, freq in enumerate(freqs):
+            # Voicing: root slightly louder, top voice slightly quieter
+            voice_vol = 1.0 if i == 0 else (0.78 if i < 3 else 0.6)
+            strike = self.strike(freq,
+                                  volume=volume * voice_vol,
+                                  brightness=brightness)
+            start = int(i * stagger * self.sr)
+            end = start + len(strike)
+            if end > len(out):
+                out = np.pad(out, (0, end - len(out)))
+            out[start:end] += strike
+        return out
+
+    def note(self, freq, duration_s, volume=1.0, brightness=0.5):
+        """
+        Single mallet strike for melody use.
+
+        duration_s is ignored beyond a minimum — the strike has its own
+        natural decay envelope (~400ms). Don't try to sustain it.
+        """
+        return self.strike(freq, volume=volume, brightness=brightness)
+
+    def sequence(self, events):
+        """
+        Render mixed events: 'chord' for rhythm role (arpeggiated),
+        'note' for melody role (single strikes).
+        """
+        if not events:
+            return np.zeros(int(self.sr), dtype=np.float32)
+
+        events = sorted(events, key=lambda e: e["time"])
+        # Extend tail to capture the reverb decay (~2s after the last event)
+        end_time = max(e["time"] + max(e["duration"], 0.6) for e in events) + 2.0
+        track = np.zeros(int(end_time * self.sr) + 1, dtype=np.float32)
+
+        for ev in events:
+            typ = ev.get("type")
+            if typ == "chord":
+                audio = self.chord(
+                    ev["name"], ev["duration"],
+                    octave=ev.get("octave", 4),
+                    volume=ev.get("volume", 0.7),
+                    brightness=ev.get("brightness", 0.5),
+                    arpeggio_ms=ev.get("arpeggio_ms", 60),
+                    direction=ev.get("direction", "up"),
+                )
+            elif typ == "note":
+                freq = note_to_hz(ev["name"])
+                audio = self.note(
+                    freq, ev["duration"],
+                    volume=ev.get("volume", 1.0),
+                    brightness=ev.get("brightness", 0.5),
+                )
+            else:
+                continue
+            track = add_at(track, audio, ev["time"])
+
+        # Apply reverb at the mix level — xylo strikes are short and dry,
+        # so a more generous wet ratio than the harp makes them sit
+        # naturally in a "room" rather than feeling like a toy.
+        track = simple_reverb(track, self.sr,
+                                room_size=0.45, damping=0.55, wet=0.32)
+        return track

tests/test_audio_pipeline.py

@@ -0,0 +1,106 @@
+"""
+Test the full audio pipeline end-to-end with a hardcoded lullaby.
+No LLM needed — uses a fixed parsed lullaby structure.
+
+Tests every (rhythm × melody) instrument pair. Use --no-voice to skip Kokoro.
+
+Run:
+    python test_audio_pipeline.py
+    python test_audio_pipeline.py --no-voice
+"""
+
+import sys
+import time
+import numpy as np
+import soundfile as sf
+
+from app import (
+    render_rhythm,
+    render_melody,
+    mix_tracks,
+    SR,
+)
+from voice import speak_lyrics
+
+
+PARSED = {
+    "bpm": 60,
+    "progression": ["D", "Bm", "G", "A"],
+    "lines": [
+        [("D", "Lucy, dear Lucy,")],
+        [("Bm", "the dark wraps the earth now,")],
+        [("G", "the cat curls up near you,")],
+        [("A", "the moon hums a soft tune...")],
+        [("D", "The stars know your name now,")],
+        [("Bm", "they call from above,")],
+        [("G", "your blanket is gentle,")],
+        [("A", "sewn warm from our love...")],
+    ],
+    "plain_lyrics": (
+        "Lucy, dear Lucy,\n"
+        "the dark wraps the earth now,\n"
+        "the cat curls up near you,\n"
+        "the moon hums a soft tune...\n"
+        "The stars know your name now,\n"
+        "they call from above,\n"
+        "your blanket is gentle,\n"
+        "sewn warm from our love..."
+    ),
+}
+
+INSTRUMENTS = ["guitar", "piano", "xylophone", "ocarina"]
+
+
+def test_pair(rhythm_instr, melody_instr, do_voice=True):
+    label = f"{rhythm_instr}+{melody_instr}"
+    print(f"\n=== {label} ===")
+
+    t0 = time.time()
+    rhythm, total_s = render_rhythm(PARSED, rhythm_instr)
+    print(f"  rhythm ({rhythm_instr}): {len(rhythm)/SR:.1f}s ({time.time()-t0:.1f}s gen)")
+
+    t0 = time.time()
+    melody = render_melody(PARSED, melody_instr)
+    print(f"  melody ({melody_instr}): {len(melody)/SR:.1f}s ({time.time()-t0:.1f}s gen)")
+
+    # Stem: rhythm + melody only
+    n = max(len(rhythm), len(melody))
+    rm = np.zeros(n, dtype=np.float32)
+    rm[:len(rhythm)] += rhythm * 0.7
+    rm[:len(melody)] += melody * 0.32
+    peak = np.abs(rm).max()
+    if peak > 0.95: rm *= 0.95 / peak
+    sf.write(f"music_test_output/test_{label}.wav", rm, SR, subtype="PCM_16")
+    print(f"  → test_{label}.wav")
+
+    if not do_voice:
+        return
+
+    t0 = time.time()
+    voice = speak_lyrics(PARSED["plain_lyrics"], target_seconds=total_s)
+    print(f"  voice: {len(voice)/SR:.1f}s ({time.time()-t0:.1f}s gen)")
+
+    mix = mix_tracks(rhythm, melody, voice)
+    sf.write(f"music_test_output/test_full_{label}.wav", mix, SR, subtype="PCM_16")
+    print(f"  → test_full_{label}.wav")
+
+
+def main():
+    no_voice = "--no-voice" in sys.argv
+
+    # Test sensible default pairings (not all 16 combos — too many files)
+    pairs = [
+        ("guitar", "ocarina"),
+        ("guitar", "xylophone"),
+        ("piano",  "ocarina"),
+        ("piano",  "xylophone"),
+        ("xylophone", "ocarina"),
+        ("ocarina", "xylophone"),
+    ]
+    for r, m in pairs:
+        test_pair(r, m, do_voice=not no_voice)
+    print("\ndone.")
+
+
+if __name__ == "__main__":
+    main()

tests/test_llm.py

@@ -0,0 +1,163 @@
+"""
+Test the LLM + parser only. No audio, no Gradio, no Kokoro.
+
+Usage:
+    python test_llm.py                          # uses LULLABY_GGUF env var or ./lullaby.gguf
+    LULLABY_GGUF=/path/to/x.gguf python test_llm.py
+"""
+
+import os
+import re
+import sys
+import time
+
+from llama_cpp import Llama
+
+
+MODEL_PATH = os.environ.get("LULLABY_GGUF", "lolaby.gguf")
+
+SYSTEM_PROMPT = (
+    "You write personalized lullabies for small children, with chord markers "
+    "and a tempo/meter header so a guitar accompaniment can be rendered. "
+    "Output only the lullaby — no preamble."
+)
+
+# Same regexes as app.py — if these match, the audio pipeline will too.
+TEMPO_RE = re.compile(r"Tempo:\s*(\d+)\s*bpm,\s*(\d+)/(\d+)", re.IGNORECASE)
+PROG_RE = re.compile(r"Progression:\s*([A-G][^\n]+)", re.IGNORECASE)
+CHORD_RE = re.compile(r"\[([A-G][^\]]*)\]\s*([^\[\n]*)")
+
+
+TEST_PROMPTS = [
+    (
+        "Mia, sleepy and comforted, 6/8",
+        "Write a lullaby for: Mia, age 3\n"
+        "Loves: her stuffed elephant Pip, the moon\n"
+        "Mood: sleepy and comforted\n"
+        "Key: C major\n"
+        "Meter: 6/8",
+    ),
+    (
+        "Theo with fear, minor key",
+        "Write a lullaby for: Theo, age 2\n"
+        "Loves: trains and tunnels\n"
+        "Fears: the dark\n"
+        "Mood: tearful, needs soothing\n"
+        "Key: A minor\n"
+        "Meter: 6/8",
+    ),
+    (
+        "Beatriz, content, 4/4",
+        "Write a lullaby for: Beatriz, age 4\n"
+        "Loves: the cat next door, songs about the sea\n"
+        "Mood: cosy and content\n"
+        "Key: D major\n"
+        "Meter: 4/4",
+    ),
+]
+
+
+def parse_lullaby(text):
+    """Same parser as the app — returns dict or raises ValueError."""
+    tempo_match = TEMPO_RE.search(text)
+    if not tempo_match:
+        raise ValueError("missing 'Tempo:' line")
+    prog_match = PROG_RE.search(text)
+    if not prog_match:
+        raise ValueError("missing 'Progression:' line")
+
+    progression = [c.strip() for c in re.split(r"\s*-\s*", prog_match.group(1)) if c.strip()]
+
+    lines = []
+    for raw in text.splitlines():
+        raw = raw.strip()
+        if not raw.startswith("["):
+            continue
+        fragments = CHORD_RE.findall(raw)
+        if fragments:
+            lines.append(fragments)
+
+    if not lines:
+        raise ValueError("no chord-marked lyric lines")
+
+    return {
+        "bpm": int(tempo_match.group(1)),
+        "meter": f"{tempo_match.group(2)}/{tempo_match.group(3)}",
+        "progression": progression,
+        "lines": lines,
+    }
+
+
+def check(label, cond, detail=""):
+    mark = "✓" if cond else "✗"
+    print(f"    {mark} {label}" + (f" — {detail}" if detail else ""))
+    return cond
+
+
+def main():
+    if not os.path.exists(MODEL_PATH):
+        print(f"ERROR: model not found at {MODEL_PATH}")
+        print("Set LULLABY_GGUF env var or put lullaby.gguf in cwd.")
+        sys.exit(1)
+
+    print(f"Loading {MODEL_PATH}...")
+    t0 = time.time()
+    llm = Llama(
+        model_path=MODEL_PATH,
+        n_ctx=1024,
+        n_threads=4,
+        n_gpu_layers=0,
+        chat_format="llama-3",
+        verbose=False,
+    )
+    print(f"Loaded in {time.time() - t0:.1f}s\n")
+
+    total_pass = 0
+    total_checks = 0
+
+    for label, prompt in TEST_PROMPTS:
+        print(f"=== {label} ===")
+        print(f"Prompt:\n{prompt}\n")
+        t0 = time.time()
+        resp = llm.create_chat_completion(
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": prompt},
+            ],
+            temperature=0.75,
+            max_tokens=400,
+            top_p=0.9,
+        )
+        gen_time = time.time() - t0
+        output = resp["choices"][0]["message"]["content"].strip()
+        print(f"Output ({gen_time:.1f}s):\n{output}\n")
+
+        # Parse it
+        try:
+            parsed = parse_lullaby(output)
+            total_pass += check("parses cleanly", True)
+            total_pass += check("tempo found", "bpm" in parsed, f"{parsed['bpm']} bpm")
+            total_pass += check("progression has ≥3 chords",
+                                len(parsed["progression"]) >= 3,
+                                str(parsed["progression"]))
+            total_pass += check("≥6 chord-marked lines",
+                                len(parsed["lines"]) >= 6,
+                                f"{len(parsed['lines'])} lines")
+
+            # Name check
+            name = prompt.split("for:")[1].split(",")[0].strip()
+            found = name.lower() in output.lower()
+            total_pass += check(f"name '{name}' in output", found)
+            total_checks += 5
+        except ValueError as e:
+            check("parses cleanly", False, str(e))
+            total_checks += 5
+
+        print()
+
+    print(f"\n=== {total_pass}/{total_checks} checks passed ===")
+    sys.exit(0 if total_pass == total_checks else 1)
+
+
+if __name__ == "__main__":
+    main()

tests/test_voice.py

@@ -0,0 +1,102 @@
+"""
+Test voice.py independently — generates a WAV file for sample lyrics
+in each soft voice. No LLM, no Gradio.
+
+Usage:
+    python test_voice.py            # test all soft voices
+    python test_voice.py af_kore    # test only the given voice id(s)
+"""
+
+import sys
+import time
+from pathlib import Path
+
+import soundfile as sf
+
+from voice import speak_lyrics, SR_TARGET, SOFT_VOICES
+
+
+SAMPLE_LYRICS = """Mia, dear Mia,
+the dark wraps the earth now,
+the cat curls up near you,
+the moon hums a soft tune...
+
+The stars know your name now,
+they call from above,
+your blanket is gentle,
+sewn warm from our love..."""
+
+
+def check_audio(audio, label):
+    """Sanity-check the returned audio."""
+    issues = []
+    if audio is None:
+        issues.append("audio is None")
+        return issues
+    if len(audio) == 0:
+        issues.append("audio is empty")
+        return issues
+
+    duration = len(audio) / SR_TARGET
+    peak = float(max(abs(audio.min()), abs(audio.max())))
+    rms = float((audio ** 2).mean() ** 0.5)
+
+    if duration < 1.0:
+        issues.append(f"too short ({duration:.2f}s)")
+    if peak < 0.001:
+        issues.append(f"silent (peak {peak:.4f})")
+    if peak > 1.0:
+        issues.append(f"clipping (peak {peak:.4f})")
+    if rms < 0.001:
+        issues.append(f"near-silent rms ({rms:.4f})")
+
+    print(f"    duration: {duration:.2f}s  peak: {peak:.3f}  rms: {rms:.3f}")
+    return issues
+
+
+def main():
+    out_dir = Path("voice_test_outputs")
+    out_dir.mkdir(exist_ok=True)
+
+    # Optional: restrict to specific voice ids passed on the command line.
+    requested = sys.argv[1:]
+    if requested:
+        voices = {v: SOFT_VOICES.get(v, v) for v in requested}
+    else:
+        voices = dict(SOFT_VOICES)
+
+    print("Testing voice.py with sample lullaby lyrics.\n")
+    print(f"Lyrics:\n{SAMPLE_LYRICS}\n")
+    print(f"Voices to test: {', '.join(voices.keys())}\n")
+
+    all_good = True
+    for voice_id, label in voices.items():
+        print(f"=== voice='{voice_id}' ({label}) ===")
+        t0 = time.time()
+        audio = speak_lyrics(
+            SAMPLE_LYRICS,
+            target_seconds=20.0,
+            voice=voice_id,
+        )
+        gen_time = time.time() - t0
+        print(f"    generated in {gen_time:.1f}s")
+
+        issues = check_audio(audio, voice_id)
+        if issues:
+            print(f"    \u2717 ISSUES: {', '.join(issues)}")
+            all_good = False
+        else:
+            print(f"    \u2713 looks good")
+            out_path = out_dir / f"voice_{voice_id}.wav"
+            sf.write(str(out_path), audio, SR_TARGET, subtype="PCM_16")
+            print(f"    saved \u2192 {out_path}")
+        print()
+
+    print(f"\n=== {'all voices OK' if all_good else 'some voices failed'} ===")
+    print(f"WAV files in: {out_dir.resolve()}")
+    print("\nListen to each and trim SOFT_VOICES in voice.py to the ones you like.")
+    sys.exit(0 if all_good else 1)
+
+
+if __name__ == "__main__":
+    main()

train/generate_dataset.py

@@ -0,0 +1,599 @@
+"""
+generate_dataset.py — build a HIGH-VARIETY lullaby fine-tuning dataset by
+distilling from a strong LLM (Anthropic Claude), with a hard anti-repetition
+gate so the result can NEVER collapse into boilerplate.
+
+WHY THIS EXISTS
+---------------
+The previous dataset was ~88% boilerplate: ~123 stock lines recombined across
+2,238 "examples" (only 12% of lines were unique). A model fine-tuned on that
+learns to reassemble a fixed kit of phrases and copies glitches like
+"dreamings" — which is exactly what we saw in both the 3B and 8B outputs.
+
+The fix is to DISTILL from a model that already writes varied, coherent
+lullabies, and to enforce variety mechanically:
+
+  1. Diverse prompt specs — large pools of names (many cultures), concrete and
+     unusual "loves", varied fears/moods/ages, all keys + meters — sampled so
+     combinations essentially never repeat.
+  2. A strong LLM writes each lullaby fresh at a creativity-friendly
+     temperature, in your EXACT output format.
+  3. DEDUP GATE: every generated lyric line is normalized and checked against
+     all lines already accepted. If too many lines overlap with existing
+     content (n-gram Jaccard), the example is rejected and regenerated. This
+     structurally prevents the boilerplate failure mode.
+  4. FORMAT GATE: each completion must parse — tempo header, [chord] markers,
+     a sensible line count — or it's regenerated.
+
+USAGE
+-----
+    export ANTHROPIC_API_KEY=sk-ant-...
+    python generate_dataset.py --n 1500 --out lullaby_dataset.jsonl
+
+    # resume/append to an existing file (keeps its lines in the dedup index):
+    python generate_dataset.py --n 500 --out lullaby_dataset.jsonl --append
+
+Notes
+-----
+- Costs real API tokens. 1,500 short completions on a small/cheap model is
+  inexpensive; check your account.
+- A clean 1,000-1,500 examples on the FAST 3B beats a dirty 2,238 on any size
+  model — you do NOT need the 8B once the data is good.
+"""
+
+import argparse
+import json
+import os
+import random
+import re
+import sys
+import time
+
+# ----------------------------------------------------------------------
+# Prompt-spec pools — broad and concrete, to drive variety at the source.
+# ----------------------------------------------------------------------
+NAMES = [
+    # deliberately multicultural so the model doesn't tie lullabies to one
+    # naming style
+    "Mia", "Theo", "Aiko", "Luca", "Noa", "Amara", "Kai", "Sofia", "Idris",
+    "Lena", "Mateo", "Yuki", "Omar", "Freya", "Diego", "Priya", "Finn",
+    "Zara", "Hana", "Niko", "Maya", "Arlo", "Ines", "Tariq", "Lila", "Oskar",
+    "Nadia", "Bo", "Esme", "Rafael", "Suri", "Milo", "Anya", "Jonah", "Leilani",
+    "Cyrus", "Wren", "Ravi", "Talia", "Soren", "Beatriz", "Émile", "Saoirse",
+    "Junie", "Cosmo", "Indra", "Pax", "Nour", "Eli", "Mei",
+]
+# DIVERSITY: a fixed list of specific loves clusters themes; but a category
+# with parenthetical *examples* also clusters, because the LLM anchors on the
+# first/easiest example we list (we saw fireflies in 20% and blankets in 25%
+# of a 20-sample test). The fix: each category carries a POOL of concrete
+# sub-topics, and make_spec() samples a SPECIFIC sub-topic to steer the LLM
+# toward — so it's pushed to "a hot-air balloon" or "a tide pool", not the
+# obvious "fireflies" every time. Combined with the theme-cap in main(), this
+# spreads coverage widely.
+LOVE_CATEGORIES = {
+    "animal/pet": [
+        "a backyard hedgehog", "a pair of ducks on the pond", "a gentle old horse",
+        "a tabby cat who naps in the sun", "a green tree frog", "a family goat",
+        "a snail with a swirly shell", "a robin that visits the windowsill",
+        "a stuffed fox named after a color", "a tortoise who moves slowly",
+        "a pony with a braided mane", "a little brown bat at dusk",
+        "a goldfish circling its bowl", "a sheepdog who herds the chickens",
+        "a ladybug on a leaf", "a stuffed whale", "a chubby garden bumblebee",
+    ],
+    "vehicle/machine": [
+        "a red tugboat in the harbor", "a hot-air balloon drifting up",
+        "a yellow digger at the building site", "the night train through the valley",
+        "a little wooden sailboat", "a cable car climbing the hill",
+        "a tractor in the far field", "a propeller plane doing loops",
+        "a windmill turning slowly", "a fire engine (quiet, parked for the night)",
+        "a paddle steamer on the river", "a kite shaped like a dragon",
+    ],
+    "nature": [
+        "the first snow settling on the fence", "a tide pool full of tiny crabs",
+        "dandelion seeds on the wind", "a mossy log in the woods",
+        "the smell of rain on warm stones", "a field of swaying barley",
+        "an acorn that might become a tree", "the frost patterns on the window",
+        "a rainbow after the storm", "pinecones under the big fir",
+        "the harvest moon low and orange", "a stream over smooth pebbles",
+        "autumn leaves spinning down",
+    ],
+    "comfort object": [
+        "a well-loved cardboard-box spaceship", "a knitted octopus with long legs",
+        "a flashlight for reading under the covers", "a tiny brass music box",
+        "a worn picture book read every night", "a pillow fort in the corner",
+        "a pair of fuzzy dinosaur slippers", "a smooth worry-stone from the beach",
+        "a paper lantern shaped like a moon", "a hand-me-down rocking chair",
+    ],
+    "activity": [
+        "stomping in rain puddles in red boots", "folding paper into cranes",
+        "skipping stones across the lake", "planting seeds in little pots",
+        "blowing soap bubbles in the yard", "spinning until dizzy on the grass",
+        "kneading dough beside a grandparent", "drawing chalk roads on the path",
+        "collecting shells along the shore", "flying down the slide at the park",
+        "humming into a paper-towel tube", "catching snowflakes on the tongue",
+    ],
+    "place": [
+        "the treehouse with the rope ladder", "grandpa's greenhouse full of tomatoes",
+        "the little library with the bean-bag corner", "the lighthouse on the point",
+        "the orchard where apples drop", "a blanket fort under the dining table",
+        "the tide line where the sand is wet", "the attic with the round window",
+        "the meadow behind the school", "the corner bakery at dawn",
+    ],
+    "person": [
+        "a big sister who tells bedtime stories", "grandpa's slow accordion tunes",
+        "an auntie who whistles while she cooks", "a baby brother's tiny yawn",
+        "a grandmother braiding hair on her lap", "a dad who does silly voices",
+        "the neighbor who shares garden strawberries", "a cousin who builds dens",
+    ],
+    "tiny wonder": [
+        "the echo in the stairwell", "shadows the curtain makes on the wall",
+        "steam curling off warm milk", "the squeak of fresh snow underfoot",
+        "raindrops racing down the window", "the click of the ceiling fan",
+        "dust motes floating in a sunbeam", "the way a spoon clinks in a cup",
+        "ripples spreading when a pebble drops",
+    ],
+    "sound": [
+        "the foghorn far out on the water", "rain drumming on a tin roof",
+        "crickets in the long summer grass", "a distant church bell at evening",
+        "the purr of a sleeping cat", "wind humming through the gate",
+        "the tick of grandfather's clock", "a mourning dove at first light",
+    ],
+    "food/treat": [
+        "porridge with a swirl of honey", "warm pear slices after supper",
+        "a single square of dark chocolate", "fresh blackberries from the bramble",
+        "buttered crumpets on a rainy day", "a cup of warm milk with nutmeg",
+        "grandma's lemon biscuits", "roasted chestnuts in winter",
+    ],
+}
+
+FEAR_TOPICS = [
+    "the dark when the light goes out",
+    "long shadows the wardrobe makes",
+    "thunder rumbling far away", "the howl of the wind at the window",
+    "fireworks banging on a holiday night",
+    "a monster they imagine under the bed",
+    "a creak in the closet at night",
+    "a parent leaving the room at bedtime",
+    "sleeping alone for the first time",
+    "the big dog barking behind the fence",
+    "the deep end of the swimming pool",
+    "high places and looking down",
+    "a bad dream about getting lost",
+    "waking and not finding anyone near",
+    None, None, None,  # ~a quarter have no fear
+]
+MOODS = [
+    "sleepy and comforted", "restless but settling", "tearful, needs soothing",
+    "cosy and content", "overtired and fussy", "calm and drowsy",
+    "wired after a long day", "missing a parent who's away",
+    "scared after a bad dream", "peaceful and almost asleep",
+    "excited but winding down", "clingy and needing reassurance",
+]
+KEYS = [
+    "C major", "G major", "D major", "A major", "E major", "F major",
+    "Bb major", "A minor", "E minor", "D minor", "B minor", "G minor",
+]
+METERS = ["6/8", "3/4", "4/4"]
+AGES = [1, 2, 2, 3, 3, 3, 4, 4, 5, 5, 6, 7]
+
+# Chord progressions keyed by tonic, for the format guidance (the LLM picks,
+# but we suggest diatonic options so the chord markers stay sensible).
+PROGRESSIONS = {
+    "C major": ["C - Am - F - G", "C - G - Am - F", "C - F - G - C", "C - Em - F - G"],
+    "G major": ["G - Em - C - D", "G - D - Em - C", "G - C - D - G"],
+    "D major": ["D - Bm - G - A", "D - A - Bm - G", "D - G - A - D"],
+    "A major": ["A - F#m - D - E", "A - E - F#m - D"],
+    "E major": ["E - C#m - A - B", "E - B - C#m - A"],
+    "F major": ["F - Dm - Bb - C", "F - C - Dm - Bb"],
+    "Bb major": ["Bb - Gm - Eb - F", "Bb - F - Gm - Eb"],
+    "A minor": ["Am - G - F - G", "Am - F - C - G", "Am - Dm - E - Am"],
+    "E minor": ["Em - C - G - D", "Em - Am - B7 - Em"],
+    "D minor": ["Dm - Bb - F - C", "Dm - Gm - A - Dm"],
+    "B minor": ["Bm - G - D - A", "Bm - Em - F#m - Bm"],
+    "G minor": ["Gm - Eb - Bb - F", "Gm - Cm - D - Gm"],
+}
+
+
+def make_spec():
+    """Sample one diverse prompt specification. We pick a love CATEGORY, then
+    a SPECIFIC sub-topic within it to steer the teacher away from clichés,
+    and record the category as a `theme` so main() can cap over-used themes."""
+    key = random.choice(KEYS)
+    love_cat = random.choice(list(LOVE_CATEGORIES.keys()))
+    love_topic = random.choice(LOVE_CATEGORIES[love_cat])
+    return {
+        "name": random.choice(NAMES),
+        "age": random.choice(AGES),
+        "theme": love_cat,                 # broad theme, for the theme-cap
+        "love_topic": love_topic,          # specific steer for the teacher
+        "fear_topic": random.choice(FEAR_TOPICS),
+        "mood": random.choice(MOODS),
+        "key": key,
+        "meter": random.choice(METERS),
+        "progression": random.choice(PROGRESSIONS[key]),
+    }
+
+
+def build_prompt(spec, love, fear):
+    """Build the STORED training prompt from the concrete love/fear the
+    teacher invented — so each training example looks exactly like a real
+    user request (matching app.py's build_prompt format)."""
+    lines = [f"Write a lullaby for: {spec['name']}, age {spec['age']}"]
+    if love:
+        lines.append(f"Loves: {love}")
+    if fear:
+        lines.append(f"Fears: {fear}")
+    lines.append(f"Mood: {spec['mood']}")
+    lines.append(f"Key: {spec['key']}")
+    lines.append(f"Meter: {spec['meter']}")
+    return "\n".join(lines)
+
+
+# ----------------------------------------------------------------------
+# The instruction we give the strong LLM (the "teacher").
+# ----------------------------------------------------------------------
+TEACHER_SYSTEM = (
+    "You are a gifted children's songwriter. You write short, original, "
+    "soothing lullabies. Every line must be grammatical and make literal "
+    "sense. Weave the child's loves and fears in NATURALLY — show a loved "
+    "thing doing what it really does (a dog curls up beside them; a train "
+    "slows for the night), and gently soothe fears away. Never force a thing "
+    "into a metaphor that doesn't make sense.\n"
+    "VARIETY IS CRITICAL. Use FRESH imagery and FRESH sentence shapes every "
+    "time. Do NOT reuse stock openers like '<Name>'s eyes are growing soft' "
+    "or '<Name> watches the ___ glow', and do NOT default to fireflies, "
+    "embroidered blankets, or twinkling stars unless explicitly asked — vary "
+    "your verbs, your line structure, and your images. Each lullaby should "
+    "feel written from scratch for THIS child.\n"
+    "SAFETY: this is for a small child at bedtime. Anything you invent must "
+    "be wholesome and age-appropriate. Never involve death, violence, "
+    "weapons, horror, substances, or anything frightening beyond a gentle, "
+    "easily-soothed childhood worry."
+)
+
+TEACHER_FORMAT = """You are given a specific LOVE (and maybe a FEAR). Use them
+as the heart of the lullaby — but render them in your own fresh words. Echo
+the given love faithfully (don't swap it for a different thing), then write
+the lullaby weaving it in.
+
+Output EXACTLY this, and nothing else:
+
+LOVE: <restate the given love in a natural phrase a parent might type>
+FEAR: <the given fear in a natural phrase, or "none">
+Tempo: <40-70>bpm, <meter>
+Progression: <the given progression>
+
+[Chord] lyric words [Chord] more words,
+[Chord] next line [Chord] continuing,
+[Chord] third line [Chord] of verse,
+[Chord] fourth line [Chord] ending...
+
+[Chord] second verse [Chord] line one,
+[Chord] line two [Chord] continuing,
+[Chord] line three [Chord] of verse,
+[Chord] final line [Chord] ending...
+
+Rules:
+- The LOVE and FEAR lines come FIRST, then Tempo, then Progression, then a
+  blank line, then the lullaby.
+- Exactly two 4-line verses (8 lyric lines total).
+- Put chord markers in [square brackets] inline before the words they cover,
+  using ONLY chords from the given progression.
+- The child's name must appear naturally in the lyric.
+- Keep lines short and singable (3-7 words).
+- VARY your opening line — do NOT start with "<Name>'s eyes are growing
+  soft" or "<Name> watches...". Find a different way in each time.
+- Everything must be wholesome and age-appropriate.
+- End the lullaby softly (trailing "..." is fine)."""
+
+
+def teacher_user(spec):
+    fear_line = (f"FEAR (soothe this gently): {spec['fear_topic']}"
+                 if spec["fear_topic"] else "FEAR: none")
+    return (
+        f"Write a lullaby for: {spec['name']}, age {spec['age']}\n"
+        f"LOVE (make this the heart of the song): {spec['love_topic']}\n"
+        f"{fear_line}\n"
+        f"Mood: {spec['mood']}\n"
+        f"Key: {spec['key']}\n"
+        f"Meter: {spec['meter']}\n"
+        f"Use this progression: {spec['progression']}\n\n"
+        + TEACHER_FORMAT
+    )
+
+
+# ----------------------------------------------------------------------
+# LLM call (Anthropic). Swap here if you prefer another provider.
+# ----------------------------------------------------------------------
+def call_teacher(spec, model, temperature):
+    import anthropic
+    client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
+    msg = client.messages.create(
+        model=model,
+        max_tokens=600,
+        temperature=temperature,
+        system=TEACHER_SYSTEM,
+        messages=[{"role": "user", "content": teacher_user(spec)}],
+    )
+    return "".join(b.text for b in msg.content if getattr(b, "type", "") == "text").strip()
+
+
+def split_teacher_output(raw):
+    """Pull the declared LOVE/FEAR header off the teacher output.
+    Returns (love, fear_or_None, completion_without_love_fear_lines)."""
+    love, fear = None, None
+    body_lines = []
+    for line in raw.split("\n"):
+        s = line.strip()
+        if love is None and s.upper().startswith("LOVE:"):
+            love = s.split(":", 1)[1].strip()
+            continue
+        if fear is None and s.upper().startswith("FEAR:"):
+            f = s.split(":", 1)[1].strip()
+            fear = None if f.lower() in ("none", "no", "n/a", "") else f
+            continue
+        body_lines.append(line)
+    # strip leading blank lines from the body
+    while body_lines and not body_lines[0].strip():
+        body_lines.pop(0)
+    return love, fear, "\n".join(body_lines).strip()
+
+
+# ----------------------------------------------------------------------
+# Validation + dedup
+# ----------------------------------------------------------------------
+def lyric_lines(completion):
+    out = []
+    for line in completion.split("\n"):
+        line = line.strip()
+        if not line or line.startswith("Tempo:") or line.startswith("Progression:"):
+            continue
+        clean = re.sub(r"\[[^\]]*\]", "", line).strip().lower()
+        clean = re.sub(r"[^\w\s]", "", clean)
+        clean = re.sub(r"\s+", " ", clean).strip()
+        if clean:
+            out.append(clean)
+    return out
+
+
+def format_ok(completion, spec):
+    if not completion.startswith("Tempo:"):
+        return False
+    if "Progression:" not in completion:
+        return False
+    if "[" not in completion or "]" not in completion:
+        return False
+    lines = lyric_lines(completion)
+    if not (6 <= len(lines) <= 10):
+        return False
+    # name must appear
+    if spec["name"].lower() not in completion.lower():
+        return False
+    # chords used in [brackets] must all be valid synth chords AND must be
+    # drawn from the progression. Exact-match each bracket token (no loose
+    # regex that could mis-split e.g. "Bbmaj7" into "Bbm").
+    prog_chords = _parse_progression_chords(spec["progression"])
+    if not prog_chords:
+        return False
+    prog_set = set(prog_chords)
+    used = {u.strip() for u in re.findall(r"\[([^\]]*)\]", completion)}
+    used.discard("")  # allow empty [] just in case, though we don't emit them
+    if not used:
+        return False
+    for ch in used:
+        if ch not in VALID_CHORDS:      # not a chord the synths understand
+            return False
+        if ch not in prog_set:          # not from the requested progression
+            return False
+    return True
+
+
+# Valid chords MUST match what the synths actually accept. The synths parse a
+# chord as <root><quality> where root in NOTE_TO_SEMI and quality in
+# CHORD_INTERVALS (synths/guitar.py, musicbox.py, piano.py all share these).
+# We build the exact set so the validator and the synths can never drift —
+# and so we don't mis-split compound chords (the old loose regex turned
+# "Bbmaj7" into "Bbm").
+_ROOTS = ["C", "C#", "Db", "D", "D#", "Eb", "E", "F",
+          "F#", "Gb", "G", "G#", "Ab", "A", "A#", "Bb", "B"]
+_QUALITIES = ["", "m", "7", "m7", "maj7", "sus2", "sus4"]
+VALID_CHORDS = {r + q for r in _ROOTS for q in _QUALITIES}
+
+
+def _parse_progression_chords(progression):
+    """Split 'Bb - Gm - Eb - F' into ['Bb','Gm','Eb','F'] using exact chord
+    matching (NOT a loose regex). Returns None if any token isn't a valid
+    synth chord."""
+    chords = []
+    for t in (tok.strip() for tok in progression.split("-")):
+        if t in VALID_CHORDS:
+            chords.append(t)
+        else:
+            return None
+    return chords
+
+
+def _ngrams(line, n=3):
+    toks = line.split()
+    if len(toks) < n:
+        return {line}
+    return {" ".join(toks[i:i+n]) for i in range(len(toks) - n + 1)}
+
+
+class DedupIndex:
+    """Tracks all accepted lyric lines (as 3-gram sets) and rejects new
+    examples that overlap too much with existing content."""
+    def __init__(self, max_line_overlap=0.5, max_song_dup_lines=2):
+        self.seen_ngrams = set()
+        self.seen_lines = set()
+        self.max_line_overlap = max_line_overlap
+        self.max_song_dup_lines = max_song_dup_lines
+
+    def index_existing(self, completion):
+        for ln in lyric_lines(completion):
+            self.seen_lines.add(ln)
+            self.seen_ngrams |= _ngrams(ln)
+
+    def too_repetitive(self, completion):
+        lines = lyric_lines(completion)
+        dup_lines = 0
+        for ln in lines:
+            if ln in self.seen_lines:
+                dup_lines += 1
+                continue
+            grams = _ngrams(ln)
+            if grams:
+                overlap = len(grams & self.seen_ngrams) / len(grams)
+                if overlap > self.max_line_overlap:
+                    dup_lines += 1
+        return dup_lines > self.max_song_dup_lines
+
+    def add(self, completion):
+        self.index_existing(completion)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--n", type=int, default=1500, help="examples to generate")
+    ap.add_argument("--out", default="lullaby_dataset.jsonl")
+    ap.add_argument("--model", default="claude-3-5-haiku-20241022",
+                    help="teacher model (cheap+good is ideal for distillation)")
+    ap.add_argument("--temperature", type=float, default=1.0)
+    ap.add_argument("--append", action="store_true",
+                    help="append to --out and seed dedup from its contents")
+    ap.add_argument("--max-attempts", type=int, default=6,
+                    help="regeneration attempts per example before skipping")
+    args = ap.parse_args()
+
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        print("ERROR: set ANTHROPIC_API_KEY", file=sys.stderr)
+        sys.exit(1)
+
+    dedup = DedupIndex()
+    mode = "a" if args.append else "w"
+    existing = 0
+    if args.append and os.path.exists(args.out):
+        for line in open(args.out):
+            try:
+                dedup.index_existing(json.loads(line)["completion"])
+                existing += 1
+            except Exception:
+                pass
+        print(f"Seeded dedup from {existing} existing examples.")
+
+    written = 0
+    rejected_fmt = 0
+    rejected_dup = 0
+    rejected_unsafe = 0
+    rejected_theme = 0
+    rejected_opener = 0
+    from collections import Counter
+    theme_counts = Counter()
+    opener_counts = Counter()
+    # No single love-theme may exceed this share of the dataset (10 themes, so
+    # an even split is 10%; we allow a little headroom at 16%).
+    theme_cap_frac = 0.16
+    t0 = time.time()
+    spins_since_write = 0
+    with open(args.out, mode) as f:
+        while written < args.n:
+            spec = make_spec()
+
+            # THEME-CAP: if this love-theme is already over its share of the
+            # dataset, skip and resample a different spec. A spin guard relaxes
+            # the cap if we can't quickly find an under-cap theme, preventing
+            # any chance of an infinite resample loop near the end of a run.
+            spins_since_write += 1
+            relax = spins_since_write > 200
+            if written >= 40 and not relax:
+                cap = max(2, int(theme_cap_frac * written))
+                if theme_counts[spec["theme"]] >= cap:
+                    rejected_theme += 1
+                    continue
+
+            accepted = False
+            for attempt in range(args.max_attempts):
+                # nudge temperature up slightly on retries for more variety
+                temp = min(1.0, args.temperature + 0.05 * attempt)
+                try:
+                    raw = call_teacher(spec, args.model, temp)
+                except Exception as e:
+                    print(f"  API error: {e}; backing off", file=sys.stderr)
+                    time.sleep(2 + attempt)
+                    continue
+                # Split off the declared concrete LOVE/FEAR header.
+                love, fear, completion = split_teacher_output(raw)
+                # SAFETY (Fix B): even though the teacher is told to stay
+                # wholesome, double-check the invented love/fear AND the
+                # lyric body. Drop anything that slips through.
+                from safety import is_safe
+                if not (is_safe(love) and is_safe(fear) and is_safe(completion)):
+                    rejected_unsafe += 1
+                    continue
+                if not format_ok(completion, spec):
+                    rejected_fmt += 1
+                    continue
+                if dedup.too_repetitive(completion):
+                    rejected_dup += 1
+                    continue
+                # OPENER-DEDUP: reject if the first lyric line uses an
+                # over-used opening shape (the model's favorite stock
+                # openers like "<name> watches..." / "...eyes are growing
+                # soft"). We normalize the opener by replacing the name with
+                # <N> and keeping the first 4 words.
+                lls = lyric_lines(completion)
+                opener = ""
+                if lls:
+                    words = lls[0].split()
+                    opener = " ".join(words[:4])
+                    opener = opener.replace(spec["name"].lower(), "<n>")
+                if opener and opener_counts[opener] >= 3:
+                    rejected_opener += 1
+                    continue
+                # accept — store a prompt built from the CONCRETE love/fear so
+                # the example mirrors a real user request.
+                rec = {"prompt": build_prompt(spec, love, fear),
+                       "completion": completion}
+                f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+                f.flush()
+                dedup.add(completion)
+                theme_counts[spec["theme"]] += 1
+                if opener:
+                    opener_counts[opener] += 1
+                written += 1
+                accepted = True
+                spins_since_write = 0
+                break
+            if not accepted:
+                # couldn't get a fresh, valid one for this spec — skip it
+                pass
+            if written and written % 25 == 0:
+                rate = written / (time.time() - t0)
+                print(f"  {written}/{args.n}  "
+                      f"(fmt-rej {rejected_fmt}, dup-rej {rejected_dup}, "
+                      f"{rate:.1f}/s)")
+
+    total = existing + written if args.append else written
+    print(f"\nDone. Wrote {written} new examples → {args.out} "
+          f"(total {total}).")
+    print(f"Rejected: {rejected_fmt} format, {rejected_dup} too-repetitive, "
+          f"{rejected_unsafe} unsafe, {rejected_theme} theme-cap, "
+          f"{rejected_opener} stock-opener.")
+    # Report final uniqueness
+    all_lines = []
+    for line in open(args.out):
+        all_lines += lyric_lines(json.loads(line)["completion"])
+    if all_lines:
+        uniq = len(set(all_lines)) / len(all_lines)
+        print(f"Line uniqueness: {uniq*100:.0f}% "
+              f"({len(set(all_lines))}/{len(all_lines)})  "
+              f"[old dataset was 12%]")
+    # Theme distribution (this run only)
+    if theme_counts:
+        print("Theme distribution:")
+        for th, c in theme_counts.most_common():
+            print(f"  {c:4d} ({100*c/max(1,written):4.0f}%)  {th}")
+
+
+if __name__ == "__main__":
+    main()

train/generate_dataset_requirements.txt

@@ -0,0 +1,4 @@
+# Dependencies for generate_dataset.py (dataset building only — NOT needed to
+# run the app). Install separately:
+#   pip install -r generate_dataset_requirements.txt
+anthropic>=0.40

utils/safety.py

@@ -0,0 +1,95 @@
+"""
+safety.py — shared content-safety screening for lullaby inputs.
+
+Used in TWO places so the rules can never diverge:
+  - app.py (Fix A): screens the USER's "loves"/"fears" free-text at runtime,
+    so a deployed-app user can't get a lullaby built around something
+    inappropriate (death, weapons, violence, etc.). Rejects with a gentle
+    message.
+  - generate_dataset.py (Fix B): screens the loves/fears that go into each
+    training example, so no training data is built around dark themes — even
+    when the teacher LLM is allowed to invent specifics.
+
+The screening is intentionally simple and conservative: a substring/word
+match against a focused list of clearly-inappropriate-for-a-child's-lullaby
+terms. It is NOT a general profanity filter or a semantic classifier — it's a
+targeted guard for the specific failure mode "user asks for a lullaby about
+death / killing / weapons / etc."
+"""
+
+import re
+
+# Terms that should never be the SUBJECT of a child's lullaby. Focused on
+# death / violence / weapons / horror / substances — not mild words. Matched
+# as whole words (so "grave" matches but "gravel" does not, "gun" matches but
+# "begun" does not).
+UNSAFE_TERMS = {
+    # death / dying
+    "death", "dead", "die", "dies", "died", "dying", "kill", "kills",
+    "killed", "killing", "murder", "murdered", "suicide", "corpse", "grave",
+    "graveyard", "coffin", "tomb", "funeral", "dead body", "hang", "hanging",
+    "noose", "drown", "drowned", "drowning",
+    # weapons / violence
+    "gun", "guns", "rifle", "pistol", "knife", "knives", "blade", "sword",
+    "bomb", "bombs", "explosion", "shoot", "shooting", "stab", "stabbed",
+    "weapon", "weapons", "blood", "bloody", "gore", "war", "battle",
+    "violence", "violent", "fight", "attack", "torture", "abuse",
+    # horror / occult
+    "demon", "demons", "devil", "satan", "hell", "ghost", "ghosts",
+    "haunted", "zombie", "zombies", "skull", "skeleton", "evil", "curse",
+    "cursed", "possessed", "sacrifice",
+    # substances / adult
+    "drug", "drugs", "cocaine", "heroin", "meth", "alcohol", "drunk",
+    "beer", "vodka", "cigarette", "cigarettes", "smoking", "weed",
+    "sex", "sexual", "naked", "nude",
+    # self-harm
+    "self harm", "self-harm", "cutting", "starve", "starving",
+}
+
+# Multi-word phrases need a substring check; single words use word-boundary.
+_MULTIWORD = {t for t in UNSAFE_TERMS if " " in t or "-" in t}
+_SINGLE = {t for t in UNSAFE_TERMS if t not in _MULTIWORD}
+_WORD_RE = re.compile(
+    r"\b(" + "|".join(re.escape(t) for t in sorted(_SINGLE, key=len, reverse=True)) + r")\b",
+    re.IGNORECASE,
+)
+
+
+def find_unsafe_terms(text):
+    """Return the list of unsafe terms found in `text` (empty if clean)."""
+    if not text:
+        return []
+    low = text.lower()
+    hits = set()
+    for phrase in _MULTIWORD:
+        if phrase in low:
+            hits.add(phrase)
+    for m in _WORD_RE.findall(low):
+        hits.add(m.lower())
+    return sorted(hits)
+
+
+def is_safe(text):
+    """True if `text` contains no unsafe terms."""
+    return len(find_unsafe_terms(text)) == 0
+
+
+def screen_inputs(loves, fears):
+    """
+    Screen the user's loves+fears for a child's lullaby.
+
+    Returns (ok, message, bad_terms):
+      ok        — True if both fields are safe
+      message   — a gentle, kid-app-appropriate rejection message (or "")
+      bad_terms — the offending terms found (for logging/debugging)
+    """
+    bad = []
+    bad += find_unsafe_terms(loves or "")
+    bad += find_unsafe_terms(fears or "")
+    bad = sorted(set(bad))
+    if bad:
+        msg = ("Let's keep the lullaby to gentle, cozy things that help with "
+               "sleep — like animals, the moon, or a favorite toy. Please "
+               "pick something soothing and try again.")
+        return (False, msg, bad)
+    return (True, "", [])

utils/trace.py

@@ -0,0 +1,255 @@
+"""
+trace.py — opt-in pipeline tracer.
+
+Records ONE complete Lolaby generation (inputs, every stage, final outputs)
+into a timestamped folder so you can publish an example trace as an HF
+Dataset for the "Sharing is Caring" hackathon badge.
+
+How to use:
+
+    LULLABY_TRACE=1 python app.py
+
+Generate a lullaby in the UI as you normally would. When the generation
+finishes, a folder is written under ./traces/<timestamp>/ containing:
+
+    trace.json            — the structured pipeline log
+    input_drawing.png     — the drawing the user gave (if any)
+    output_lullaby.wav    — the final audio
+    README.md             — short note pointing at trace.json
+
+That folder is what you upload to a Hugging Face Dataset.
+
+Privacy posture:
+  - DISABLED by default (do nothing unless LULLABY_TRACE is set).
+  - Even when enabled, set LULLABY_TRACE_NO_IMAGES=1 to skip saving the
+    input drawing (records the trace structure but not the actual image).
+
+Design note:
+  This is deliberately a module-level buffer accumulated by side-effects
+  rather than a context manager threaded through every call site. The
+  goal is MINIMAL changes to app.py — instrumentation calls are one
+  line each at the places that matter.
+"""
+
+import json
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+
+
+ENABLED = os.environ.get("LULLABY_TRACE", "").lower() in ("1", "true", "yes")
+SAVE_IMAGES = os.environ.get("LULLABY_TRACE_NO_IMAGES", "").lower() not in ("1", "true", "yes")
+TRACE_ROOT = Path(os.environ.get("LULLABY_TRACE_DIR", "./traces"))
+
+
+# Current run's accumulated state. Reset at the start of each generation
+# via `begin()`. Read by `finalize()` at the end.
+_buf = {}
+_t0 = None
+
+
+def is_enabled():
+    return ENABLED
+
+
+def begin():
+    """Reset the buffer at the start of a new generation. Cheap no-op if
+    tracing is disabled, so it's safe to call unconditionally."""
+    global _buf, _t0
+    if not ENABLED:
+        return
+    _t0 = time.monotonic()
+    _buf = {
+        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "stages": {},
+        "stage_timings_ms": {},
+    }
+
+
+def stage(name, **fields):
+    """Record a stage's metadata. Each call merges into stages[name]."""
+    if not ENABLED:
+        return
+    if name not in _buf["stages"]:
+        _buf["stages"][name] = {}
+    _buf["stages"][name].update(fields)
+    # Mark when this stage was last updated, relative to begin().
+    if _t0 is not None:
+        _buf["stage_timings_ms"][name] = round((time.monotonic() - _t0) * 1000)
+
+
+def set_inputs(**kw):
+    """Record the user-facing inputs (name, age, loves, fears, etc.).
+    Image arrays are NOT stored here — `save_input_drawing` handles them."""
+    if not ENABLED:
+        return
+    _buf["inputs"] = {k: v for k, v in kw.items() if v not in (None, "")}
+
+
+def finalize(output_audio=None, sample_rate=44100, error=None):
+    """Write the trace folder. Called at the end of a generation, whether
+    or not it succeeded. Returns the trace folder path (or None if
+    tracing is disabled)."""
+    if not ENABLED:
+        return None
+    if _t0 is not None:
+        _buf["total_wall_time_ms"] = round((time.monotonic() - _t0) * 1000)
+    if error is not None:
+        _buf["error"] = str(error)
+
+    TRACE_ROOT.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.utcnow().strftime("%Y-%m-%d_%H-%M-%S")
+    folder = TRACE_ROOT / stamp
+    folder.mkdir(exist_ok=True)
+
+    # Write trace.json
+    with open(folder / "trace.json", "w") as f:
+        json.dump(_buf, f, indent=2, default=_json_safe)
+
+    # Write output audio if provided
+    if output_audio is not None:
+        try:
+            import soundfile as sf
+            import numpy as np
+            audio = output_audio
+            if isinstance(audio, np.ndarray):
+                sf.write(folder / "output_lullaby.wav", audio, sample_rate)
+        except Exception as e:
+            print(f"[trace] could not write audio: {e}")
+
+    # Write a small README pointing at the trace file
+    readme = folder / "README.md"
+    readme.write_text(_README_TEMPLATE.format(stamp=stamp))
+
+    print(f"[trace] wrote {folder}/")
+    return folder
+
+
+def save_input_drawing(image_array):
+    """Save the input drawing as input_drawing.png in the *current* run's
+    folder. Called inside the pipeline as soon as we know the image. Has
+    to be deferred-write because we don't know the folder name until
+    finalize() — so we stash the array here and write on finalize."""
+    if not ENABLED or not SAVE_IMAGES:
+        return
+    if image_array is None:
+        return
+    _buf["_pending_image"] = image_array
+
+
+def _flush_image(folder):
+    """Internal: write the stashed image to the trace folder."""
+    arr = _buf.get("_pending_image")
+    if arr is None:
+        return
+    try:
+        from PIL import Image
+        import numpy as np
+        if isinstance(arr, np.ndarray):
+            if arr.ndim == 2:
+                img = Image.fromarray(arr).convert("RGB")
+            else:
+                img = Image.fromarray(arr[..., :3].astype(np.uint8))
+            img.save(folder / "input_drawing.png")
+        elif isinstance(arr, Image.Image):
+            arr.save(folder / "input_drawing.png")
+    except Exception as e:
+        print(f"[trace] could not write input drawing: {e}")
+    # Strip the binary out of the JSON-bound buffer.
+    del _buf["_pending_image"]
+
+
+def _json_safe(o):
+    """Last-resort encoder for objects that aren't JSON-serializable."""
+    try:
+        import numpy as np
+        if isinstance(o, np.ndarray):
+            return f"<ndarray shape={o.shape} dtype={o.dtype}>"
+        if isinstance(o, (np.integer,)):
+            return int(o)
+        if isinstance(o, (np.floating,)):
+            return float(o)
+    except ImportError:
+        pass
+    return str(o)
+
+
+_README_TEMPLATE = """# Lolaby — example generation trace
+
+Captured: {stamp} (UTC)
+
+## Files
+
+- `trace.json` — full pipeline log: inputs, every stage's prompts and
+  outputs, stage timings, and the parsed lyric structure.
+- `input_drawing.png` — the drawing the user gave Lola at the start of
+  this generation (omitted if no drawing was provided, or if traces
+  were captured with `LULLABY_TRACE_NO_IMAGES=1`).
+- `output_lullaby.wav` — the audio Lola produced. WAV, 44.1 kHz mono.
+
+## Note on reproducibility
+
+This trace records one real generation end-to-end. The deterministic
+stages (vision-model output with `do_sample=False`, DSP synth rendering
+from parsed lyrics) will reproduce given the same inputs. The sampling
+stages (the lyric model at `temperature=0.85`, Kokoro TTS) will produce
+*similar but not identical* output on re-run — they're inherently
+stochastic. The trace is a witness of one run, not a recipe.
+
+## Pipeline at a glance
+
+```
+drawing ─▶ MiniCPM-V 4.6 ─▶ "what Lola saw"
+                                  │
+                + name, fears, mood, instruments
+                                  ▼
+                Fine-tuned Llama 3.2 3B (GGUF, llama.cpp)
+                                  │
+                          parsed lyric + chords + tempo
+                                  │
+                ┌─────────────────┴─────────────────┐
+                ▼                                   ▼
+          Kokoro TTS                       DSP synths (custom)
+                └─────────────────┬─────────────────┘
+                                  ▼
+                            output_lullaby.wav
+```
+"""
+
+
+# Patch finalize() to call _flush_image at the right point. We do it this
+# way to keep the begin/stage/finalize public API tiny.
+_orig_finalize = finalize
+def finalize(output_audio=None, sample_rate=44100, error=None):  # noqa: F811
+    if not ENABLED:
+        return None
+    if _t0 is not None:
+        _buf["total_wall_time_ms"] = round((time.monotonic() - _t0) * 1000)
+    if error is not None:
+        _buf["error"] = str(error)
+
+    TRACE_ROOT.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.utcnow().strftime("%Y-%m-%d_%H-%M-%S")
+    folder = TRACE_ROOT / stamp
+    folder.mkdir(exist_ok=True)
+
+    # Pull the stashed image out before we serialize the rest to JSON.
+    _flush_image(folder)
+
+    with open(folder / "trace.json", "w") as f:
+        json.dump(_buf, f, indent=2, default=_json_safe)
+
+    if output_audio is not None:
+        try:
+            import soundfile as sf
+            import numpy as np
+            audio = output_audio
+            if isinstance(audio, np.ndarray):
+                sf.write(folder / "output_lullaby.wav", audio, sample_rate)
+        except Exception as e:
+            print(f"[trace] could not write audio: {e}")
+
+    (folder / "README.md").write_text(_README_TEMPLATE.format(stamp=stamp))
+    print(f"[trace] wrote {folder}/")
+    return folder