Initial Kids Rhyme Studio setup

README.md

@@ -1,15 +1,115 @@
 ---
 title: Kids Rhyme Studio
-emoji: 😻
-colorFrom: yellow
-colorTo: red
+emoji: 🎵
+colorFrom: pink
+colorTo: yellow
 sdk: gradio
 sdk_version: 6.28.0
-python_version: '3.12'
+python_version: 3.12.12
 app_file: app.py
 pinned: false
-license: mit
-short_description: Personalized kids’ songs in English, Spanish, Telugu & Germa
+license: other
+short_description: Make a child's word rhyme and hear it sung as a song
+preload_from_hub:
+  - ACE-Step/acestep-v15-xl-turbo-diffusers
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Kids Rhyme Studio 🎵
+
+Turn a child's words into an **original sung song**. Enter a first name, **one
+to ten words**, and a song theme. Pick **English, Spanish,
+Telugu, or German**, then click **Make my rhyme**. Edit the lines if you like,
+then click **Sing my rhyme** to hear and download a WAV file.
+
+The song is generated with [ACE-Step 1.5](https://huggingface.co/ACE-Step/acestep-v15-xl-turbo-diffusers).
+It creates a vocal performance with accompaniment from the supplied lyrics;
+this is not spoken narration over music. Generated singing can sometimes
+mispronounce or change a word, especially in less common languages. Listen
+and regenerate if needed. No speech or instrumental-only fallback is used.
+All entered words appear in the written rhyme; longer lists produce a longer song.
+
+## Pick a song theme
+
+Choose **Good Habits**, **Kindness & Sharing**, **Bedtime**, **Counting**,
+**Colors & Shapes**, **Animals & Nature**, or **Confidence & Trying Again**.
+Each preset has a lesson and teaching lines in all four languages.
+
+Use the optional **Theme prompt** to be more specific, such as “Teach washing
+hands before meals and putting toys away.” Choose **Custom theme** to supply
+your own topic, such as “Feeling brave on the first day of school.”
+Custom themes require a prompt. For the built-in writer, write supplied words
+and prompts in your selected language; it preserves your text without translating it.
+The optional AI writer is instructed to interpret your topic in the chosen language.
+
+The selected language is passed explicitly to ACE-Step as `en`, `es`, `te`,
+or `de`, alongside the lyrics and an instruction to sing in that language.
+This configures generation; it does not verify the language of the finished audio.
+If you change your language, theme, words, name, or mood after generating the
+rhyme, click **Make my rhyme** again before singing.
+
+The built-in rhyme writer needs no token. The optional AI writer gives more
+varied lyrics when a parent supplies `HF_TOKEN`; it sends the name, words, theme,
+and prompt to a hosted model. The singing model runs on your Space's GPU without an
+Inference Providers token.
+
+## Set up a Hugging Face Space
+
+1. Create a [new Space](https://huggingface.co/new-space), name it
+   `kids-rhyme-studio`, and choose **Gradio** as the SDK.
+2. In **Settings → Hardware**, select **ZeroGPU**. CPU Basic cannot generate
+   the song. ZeroGPU provides shared GPU time subject to its usage quota.
+3. Upload these six files to the **root** of the Space: `README.md`,
+   `app.py`, `rhyme_engine.py`, `themes.py`, `audio_engine.py`, and `requirements.txt`.
+   The build preloads the singing model (roughly 11 GB), so the first build
+   may take some time.
+4. In the **App** tab, try the example words, click **Make my rhyme**, and
+   then **Sing my rhyme**. Wait for the GPU queue and the song to finish.
+5. Optional: Under **Settings → Variables and secrets**, add `HF_TOKEN` as
+   a **secret** if you want the optional AI lyric writer. Otherwise the
+   built-in writer works as is; never paste a token into source files.
+
+For an existing Space, upload all six files and switch its hardware to
+ZeroGPU before testing the song. The app shows an error when sung generation
+is unavailable; it does not substitute spoken audio.
+
+## Run locally
+
+Use Python 3.12 and a CUDA GPU. Install a compatible CUDA-enabled PyTorch
+(version 2.8 or newer) for your system, then run:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install gradio==6.28.0 -r requirements.txt
+python app.py
+```
+
+Open the address printed by Gradio. The large song model downloads at first
+startup. A local machine without a GPU can still write rhymes, but cannot
+sing them.
+
+## Notes for parents
+
+- Read and listen to the result before sharing it with a child. The simple
+  word guard is not a complete child-safety filter, and generated audio can
+  differ from the displayed words.
+- Use a nickname. The app has no account or rhyme database. The optional AI
+  writer is off by default and sends entered text to its hosted provider only
+  when enabled with a configured token.
+- The model's four language codes are `en`, `es`, `te`, and `de`. Singing
+  quality and pronunciation vary by language and input.
+- ZeroGPU has daily usage limits and a queue. The Space requires Python
+  3.12.12 (or another version currently supported by ZeroGPU), a compatible
+  PyTorch runtime, and sufficient model download time and disk space.
+- To change the optional AI writer, set `LYRICS_MODEL` to another supported
+  chat model; its default is `Qwen/Qwen3-4B-Instruct-2507`.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `app.py` | Simple word form, editable rhyme, and song player |
+| `rhyme_engine.py` | Input checks, four-language templates, optional AI lyrics |
+| `themes.py` | Suggested lessons and teaching lines in four languages |
+| `audio_engine.py` | ACE-Step sung song generation on ZeroGPU |
+| `requirements.txt` | Song-model Python dependencies |