README.md

---
title: Kids Rhyme Studio
emoji: 🎵
colorFrom: pink
colorTo: yellow
sdk: gradio
sdk_version: 6.28.0
python_version: 3.12.12
app_file: app.py
pinned: false
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
---

# 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 |