@rosetears/aili-pi 0.1.0

package/skills/frontend-dev/canvas-fonts/YoungSerif-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2023 The Young Serif Project Authors (https://github.com/noirblancrouge/YoungSerif)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/skills/frontend-dev/references/asset-prompt-guide.md

@@ -0,0 +1,43 @@
+# Prompt Engineering Guide
+
+## Image Prompts
+
+- Be specific about composition: "left-aligned subject with negative space on the right for text overlay"
+- Specify lighting: "soft studio lighting", "golden hour backlight", "flat diffused light"
+- Include style modifiers: "editorial photography", "3D render", "flat vector illustration"
+- Add technical specs: "4K resolution, sharp focus, shallow depth of field"
+- For web assets: always mention "clean background", "web-optimized", "high contrast for readability"
+- **NEVER** include text in image prompts unless explicitly requested — AI text rendering is unreliable
+
+## Video Prompts
+
+- Use MiniMax camera commands in brackets: `[Push in]`, `[Truck left]`, `[Tracking shot]`, etc.
+- Describe scene, subject, lighting, and mood — the API auto-optimizes prompts by default
+- For web backgrounds: keep 6s duration, add `[Static shot]` for stability
+- Max 2,000 characters
+
+## Audio / TTS
+
+- Specify genre, tempo (BPM), mood, and instruments
+- For background music: "no vocals, suitable for background, not distracting"
+- For sound effects: be extremely specific about the sound event
+- For TTS: choose voice matching content language and speaker gender
+
+## Preset Shortcuts
+
+| Shortcut | Spec |
+|----------|------|
+| `hero` | 16:9 (1280x720) image, cinematic, text-safe space |
+| `thumb` | 1:1 (1024x1024) image, centered subject |
+| `icon` | 1:1 (1024x1024), flat style, clean background |
+| `avatar` | 1:1 (1024x1024), portrait, circular crop ready |
+| `banner` | 21:9 (1344x576), OG/social banner |
+| `portrait` | 2:3 (832x1248), vertical portrait |
+| `mobile` | 9:16 (720x1280), mobile fullscreen |
+| `bg-video` | 768P, 6s, `[Static shot]`, MiniMax Hailuo-2.3 |
+| `video` | 768P, 6s, MiniMax Hailuo-2.3, prompt auto-optimized |
+| `video-hd` | 1080P, 6s, MiniMax Hailuo-2.3 |
+| `bgm` | 30s background music, no vocals, loopable |
+| `sfx` | Short sound effect, < 3s |
+| `tts` | Text-to-speech, MiniMax HD, MP3 |
+| `narration` | Expressive narration voice, MiniMax |

package/skills/frontend-dev/references/env-setup.md

@@ -0,0 +1,33 @@
+# Getting Started
+
+## 1. Set API key
+
+```bash
+export MINIMAX_API_KEY="<paste-your-key-here>"
+```
+
+## 2. Install dependencies
+
+```bash
+pip install requests
+
+# FFmpeg (optional, for audio post-processing)
+# macOS:
+brew install ffmpeg
+# Ubuntu:
+sudo apt install ffmpeg
+```
+
+## 3. Quick test
+
+```bash
+python scripts/minimax_tts.py "Hello world" -o test.mp3
+```
+
+If successful, you'll see `OK: xxxxx bytes -> test.mp3`.
+
+## Next steps
+
+- **Voice selection**: See [minimax-voice-catalog.md](minimax-voice-catalog.md)
+- **TTS workflows**: See [minimax-tts-guide.md](minimax-tts-guide.md)
+- **Troubleshooting**: See [troubleshooting.md](troubleshooting.md)

package/skills/frontend-dev/references/minimax-cli-reference.md

@@ -0,0 +1,133 @@
+# Provider Reference — MiniMax
+
+All asset generation uses MiniMax API. Env: `MINIMAX_API_KEY` (required).
+
+## Audio (Sync TTS)
+
+**Script:** `scripts/minimax_tts.py`
+
+```bash
+python scripts/minimax_tts.py "Hello world" -o output.mp3
+python scripts/minimax_tts.py "你好" -o hi.mp3 -v female-shaonv
+python scripts/minimax_tts.py "Welcome" -o out.wav -v male-qn-jingying --speed 0.8 --format wav
+```
+
+**Model:** `speech-2.8-hd` (default).
+
+| Flag | Default | Range / Options |
+|------|---------|-----------------|
+| `-o` | (required) | Output file path |
+| `-v` | `male-qn-qingse` | Voice ID |
+| `--model` | `speech-2.8-hd` | speech-2.8-hd / speech-2.8-turbo / speech-2.6-hd / speech-2.6-turbo |
+| `--speed` | 1.0 | 0.5–2.0 |
+| `--volume` | 1.0 | 0.1–10 |
+| `--pitch` | 0 | -12 to 12 |
+| `--emotion` | (auto) | happy / sad / angry / fearful / disgusted / surprised / calm / fluent / whisper |
+| `--format` | mp3 | mp3 / wav / flac |
+| `--lang` | auto | Language boost |
+
+**Programmatic:**
+```python
+from minimax_tts import tts
+audio_bytes = tts("Hello", voice_id="female-shaonv")
+```
+
+
+## Video (Text-to-Video)
+
+**Script:** `scripts/minimax_video.py`
+
+```bash
+python scripts/minimax_video.py "A cat playing piano" -o cat.mp4
+python scripts/minimax_video.py "Ocean waves [Truck left]" -o waves.mp4 --duration 10
+python scripts/minimax_video.py "City skyline [Push in]" -o city.mp4 --resolution 1080P
+```
+
+**Model:** `MiniMax-Hailuo-2.3` (default). Async: script handles create → poll → download automatically.
+
+| Flag | Default | Options |
+|------|---------|---------|
+| `-o` | (required) | Output file path (.mp4) |
+| `--model` | `MiniMax-Hailuo-2.3` | MiniMax-Hailuo-2.3 / MiniMax-Hailuo-02 / T2V-01-Director / T2V-01 |
+| `--duration` | 6 | 6 / 10 (10s only at 768P with Hailuo models) |
+| `--resolution` | 768P | 720P / 768P / 1080P (1080P only 6s) |
+| `--no-optimize` | false | Disable prompt auto-optimization |
+| `--poll-interval` | 10 | Seconds between status checks |
+| `--max-wait` | 600 | Max wait time in seconds |
+
+**Camera commands** — insert `[Command]` in prompt: `[Push in]`, `[Truck left]`, `[Pan right]`, `[Zoom out]`, `[Static shot]`, `[Tracking shot]`, etc.
+
+**Programmatic:**
+```python
+from minimax_video import generate
+generate("A cat playing piano", "cat.mp4", model="MiniMax-Hailuo-2.3", duration=6)
+```
+
+See [minimax-video-guide.md](minimax-video-guide.md) for full camera command list and model compatibility.
+
+## Image (Text-to-Image)
+
+**Script:** `scripts/minimax_image.py`
+
+```bash
+python scripts/minimax_image.py "A cat astronaut in space" -o cat.png
+python scripts/minimax_image.py "Mountain landscape" -o hero.png --ratio 16:9
+python scripts/minimax_image.py "Product icons, flat style" -o icons.png -n 4 --seed 42
+```
+
+**Model:** `image-01`. Sync: returns image URL (or base64) immediately.
+
+| Flag | Default | Options |
+|------|---------|---------|
+| `-o` | (required) | Output file path (.png/.jpg) |
+| `--ratio` | 1:1 | 1:1 / 16:9 / 4:3 / 3:2 / 2:3 / 3:4 / 9:16 / 21:9 |
+| `-n` | 1 | Number of images (1–9) |
+| `--seed` | (random) | Seed for reproducibility |
+| `--optimize` | false | Enable prompt auto-optimization |
+| `--base64` | false | Return base64 instead of URL |
+
+**Batch output:** with `-n > 1`, files are named `out-0.png`, `out-1.png`, etc.
+
+**Programmatic:**
+```python
+from minimax_image import generate_image, download_and_save
+result = generate_image("A cat in space", aspect_ratio="16:9")
+download_and_save(result["data"]["image_urls"][0], "cat.png")
+```
+
+See [minimax-image-guide.md](minimax-image-guide.md) for ratio dimensions and details.
+
+## Music (Text-to-Music)
+
+**Script:** `scripts/minimax_music.py`
+
+```bash
+python scripts/minimax_music.py --prompt "Indie folk, melancholic" --lyrics "[verse]\nStreetlights flicker" -o song.mp3
+python scripts/minimax_music.py --prompt "Upbeat pop, energetic" --auto-lyrics -o pop.mp3
+python scripts/minimax_music.py --prompt "Jazz piano, smooth, relaxing" --instrumental -o jazz.mp3
+```
+
+**Model:** `music-2.5+` (default). Sync: returns audio hex or URL.
+
+| Flag | Default | Options |
+|------|---------|---------|
+| `-o` | (required) | Output file path (.mp3/.wav) |
+| `--prompt` | (empty) | Music description: style, mood, scenario (max 2000 chars) |
+| `--lyrics` | (empty) | Song lyrics with structure tags (max 3500 chars) |
+| `--lyrics-file` | (empty) | Read lyrics from file |
+| `--model` | `music-2.5+` | music-2.5+ / music-2.5 |
+| `--instrumental` | false | Generate instrumental only (no vocals, music-2.5+ only) |
+| `--auto-lyrics` | false | Auto-generate lyrics from prompt |
+| `--format` | mp3 | mp3 / wav / pcm |
+| `--sample-rate` | 44100 | 16000 / 24000 / 32000 / 44100 |
+| `--bitrate` | 256000 | 32000 / 64000 / 128000 / 256000 |
+
+**Lyrics structure tags:** `[Intro]`, `[Verse]`, `[Pre Chorus]`, `[Chorus]`, `[Interlude]`, `[Bridge]`, `[Outro]`, `[Post Chorus]`, `[Transition]`, `[Break]`, `[Hook]`, `[Build Up]`, `[Inst]`, `[Solo]`
+
+**Programmatic:**
+```python
+from minimax_music import generate_music
+result = generate_music(prompt="Jazz piano", is_instrumental=True)
+with open("jazz.mp3", "wb") as f:
+    f.write(result["audio_bytes"])
+```

package/skills/frontend-dev/references/minimax-image-guide.md

@@ -0,0 +1,65 @@
+# Image Generation Guide
+
+## CLI usage
+
+```bash
+# Basic (1:1, 1024x1024)
+python scripts/minimax_image.py "A cat astronaut floating in space" -o cat.png
+
+# 16:9 for hero banner
+python scripts/minimax_image.py "Mountain landscape at golden hour" -o hero.png --ratio 16:9
+
+# Batch: 4 images at once
+python scripts/minimax_image.py "Minimalist product icon" -o icons.png -n 4
+
+# With seed for reproducibility
+python scripts/minimax_image.py "Abstract gradient background" -o bg.png --seed 42
+
+# Enable prompt optimization
+python scripts/minimax_image.py "a dog" -o dog.png --optimize
+
+# Base64 mode (no URL download, save directly)
+python scripts/minimax_image.py "Logo concept" -o logo.png --base64
+```
+
+## Programmatic usage
+
+```python
+from minimax_image import generate_image, download_and_save
+
+# Generate and get URL
+result = generate_image("A cat in space", aspect_ratio="16:9")
+url = result["data"]["image_urls"][0]
+download_and_save(url, "cat.png")
+
+# Generate multiple
+result = generate_image("Icon design", n=4, aspect_ratio="1:1")
+for i, url in enumerate(result["data"]["image_urls"]):
+    download_and_save(url, f"icon-{i}.png")
+```
+
+## Model
+
+Currently only `image-01`.
+
+## Aspect ratios & dimensions
+
+| Ratio | Pixels | Use case |
+|-------|--------|----------|
+| `1:1` | 1024x1024 | Avatar, icon, square thumbnail |
+| `16:9` | 1280x720 | Hero banner, video thumbnail |
+| `4:3` | 1152x864 | Standard landscape |
+| `3:2` | 1248x832 | Photo-style |
+| `2:3` | 832x1248 | Portrait, mobile |
+| `3:4` | 864x1152 | Portrait card |
+| `9:16` | 720x1280 | Mobile fullscreen, story |
+| `21:9` | 1344x576 | Ultra-wide banner |
+
+Custom dimensions also supported: width/height in [512, 2048], must be divisible by 8.
+
+## Limits
+
+- Prompt: max 1,500 characters
+- Batch: 1–9 images per request
+- URL expires after 24 hours (use `--base64` to avoid expiry)
+- Seed: set for reproducible results across identical prompts

package/skills/frontend-dev/references/minimax-music-guide.md

@@ -0,0 +1,216 @@
+# Music Generation Guide
+
+## CLI Usage
+
+```bash
+# Instrumental (no vocals)
+python scripts/minimax_music.py --prompt "Jazz piano, smooth, relaxing" --instrumental -o jazz.mp3
+
+# With custom lyrics
+python scripts/minimax_music.py --prompt "Indie folk, melancholic" --lyrics "[verse]\nStreetlights flicker\nOn empty roads" -o song.mp3
+
+# Auto-generate lyrics from prompt
+python scripts/minimax_music.py --prompt "Upbeat pop, energetic, summer vibes" --auto-lyrics -o pop.mp3
+
+# From lyrics file
+python scripts/minimax_music.py --prompt "Soulful blues, rainy night" --lyrics-file lyrics.txt -o blues.mp3
+
+# Custom audio settings
+python scripts/minimax_music.py --prompt "Lo-fi beats" --instrumental -o lofi.wav --format wav --sample-rate 44100 --bitrate 256000
+```
+
+## Programmatic Usage
+
+```python
+from minimax_music import generate_music
+
+# Instrumental
+result = generate_music(prompt="Jazz piano, smooth", is_instrumental=True)
+with open("jazz.mp3", "wb") as f:
+    f.write(result["audio_bytes"])
+
+# With lyrics
+result = generate_music(
+    prompt="Indie folk, acoustic guitar",
+    lyrics="[verse]\nWalking through the rain\n[chorus]\nI'll find my way home",
+)
+
+# Auto-generate lyrics
+result = generate_music(
+    prompt="Upbeat pop, summer anthem",
+    lyrics_optimizer=True,
+)
+
+# Access metadata
+print(f"Duration: {result['duration']}ms")
+print(f"Sample rate: {result['sample_rate']}")
+print(f"Size: {result['size']} bytes")
+```
+
+## Models
+
+| Model | Features |
+|-------|----------|
+| `music-2.5+` | Recommended. Supports instrumental mode, complete song structures, hi-fi audio |
+| `music-2.5` | Standard model. No instrumental mode |
+
+## Prompt Writing
+
+The `prompt` parameter describes music style using comma-separated descriptors:
+
+| Category | Examples |
+|----------|----------|
+| Genre | Blues, Pop, Rock, Jazz, Electronic, Hip-hop, Folk, Classical |
+| Mood | Soulful, Melancholy, Upbeat, Energetic, Peaceful, Dark, Nostalgic |
+| Scenario | Rainy night, Summer day, Road trip, Late night, Sunrise |
+| Instrumentation | Electric guitar, Piano, Acoustic, Synthesizer, Strings |
+| Vocal type | Male vocals, Female vocals, Soft vocals, Powerful vocals |
+| Tempo | Slow tempo, Fast tempo, Mid-tempo, Relaxed |
+
+**Example prompts:**
+```
+"Soulful Blues, Rainy Night, Melancholy, Male Vocals, Slow Tempo"
+"Upbeat Pop, Summer Vibes, Female Vocals, Energetic, Synth-heavy"
+"Lo-fi Hip-hop, Chill, Relaxed, Instrumental, Piano samples"
+"Cinematic Orchestral, Epic, Building tension, Strings and Brass"
+```
+
+## Lyrics Format
+
+Use structure tags in brackets to organize song sections:
+
+### Structure Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `[Intro]` | Opening section (can be instrumental) |
+| `[Verse]` / `[Verse 1]` | Story/narrative sections |
+| `[Pre-Chorus]` | Build-up before chorus |
+| `[Chorus]` | Main hook, typically repeated |
+| `[Post Chorus]` | Extension after chorus |
+| `[Bridge]` | Contrasting section near end |
+| `[Interlude]` | Instrumental break |
+| `[Solo]` | Instrumental solo (add direction: "slow, bluesy") |
+| `[Outro]` | Closing section |
+| `[Break]` | Short pause or transition |
+| `[Hook]` | Catchy repeated phrase |
+| `[Build Up]` | Tension building section |
+| `[Inst]` | Instrumental section |
+| `[Transition]` | Section change |
+
+### Backing Vocals & Directions
+
+Use parentheses for backing vocals or performance notes:
+```
+(Ooh, yeah)
+(Harmonize)
+(Whispered)
+(Fade out...)
+```
+
+### Example Lyrics
+
+```
+[Intro]
+(Soft piano)
+
+[Verse 1]
+Streetlights flicker on empty roads
+The rain keeps falling, the wind still blows
+I'm walking home with nowhere to go
+Just memories of what I used to know
+
+[Pre-Chorus]
+And I can feel it coming back to me
+(Coming back to me)
+
+[Chorus]
+Under the neon lights tonight
+I'm searching for what feels right
+(Oh, feels right)
+These city streets will guide me home
+I'm tired of feeling so alone
+
+[Verse 2]
+Coffee shops and midnight trains
+The faces change but the feeling remains
+...
+
+[Bridge]
+Maybe tomorrow will be different
+Maybe I'll finally understand
+(Understand...)
+
+[Solo]
+(Slow, mournful, bluesy guitar)
+
+[Outro]
+(Fade out...)
+Under the neon lights...
+```
+
+## Audio Settings
+
+| Parameter | Options | Default | Notes |
+|-----------|---------|---------|-------|
+| `format` | mp3, wav, pcm | mp3 | WAV for highest quality |
+| `sample_rate` | 16000, 24000, 32000, 44100 | 44100 | 44100 recommended |
+| `bitrate` | 32000, 64000, 128000, 256000 | 256000 | Higher = better quality |
+
+## Generation Modes
+
+### 1. Instrumental Only
+```bash
+python scripts/minimax_music.py --prompt "Ambient electronic, space theme" --instrumental -o ambient.mp3
+```
+- Requires `music-2.5+` model
+- Only `prompt` needed, no lyrics
+
+### 2. With Custom Lyrics
+```bash
+python scripts/minimax_music.py --prompt "Pop ballad, emotional" --lyrics "[verse]\nYour lyrics here" -o ballad.mp3
+```
+- Provide both `prompt` (style) and `lyrics` (words + structure)
+
+### 3. Auto-Generated Lyrics
+```bash
+python scripts/minimax_music.py --prompt "Rock anthem about freedom" --auto-lyrics -o rock.mp3
+```
+- System generates lyrics from prompt
+- Good for quick generation when lyrics aren't critical
+
+## Limits
+
+- **Prompt:** max 2,000 characters
+- **Lyrics:** 1–3,500 characters
+- **Duration:** ~25-30 seconds per generation (varies)
+- **URL expiration:** 24 hours (when using URL output mode)
+
+## Best Practices
+
+1. **Layer style descriptors** — Combine genre + mood + instrumentation for precise results
+2. **Use structure tags** — Even simple `[verse]` `[chorus]` improves arrangement
+3. **Include backing vocal cues** — `(Ooh)`, `(Yeah)` add production polish
+4. **Match prompt to lyrics mood** — Conflicting prompt/lyrics produce inconsistent results
+5. **Instrumental for backgrounds** — Use `--instrumental` for BGM, avoiding vocal distractions
+6. **High bitrate for production** — Use 256000 for final assets, lower for drafts
+
+## Common Use Cases
+
+| Use Case | Command |
+|----------|---------|
+| Background music | `--prompt "Lo-fi, calm, ambient" --instrumental` |
+| Landing page hero | `--prompt "Cinematic, inspiring, building" --instrumental` |
+| Podcast intro | `--prompt "Upbeat, energetic, short" --instrumental` |
+| Demo song | `--prompt "Pop, catchy" --auto-lyrics` |
+| Custom jingle | `--prompt "Happy, bright, corporate" --lyrics "[hook]\nYour brand name"` |
+
+## Error Handling
+
+| Error Code | Meaning | Solution |
+|------------|---------|----------|
+| 1002 | Rate limit | Wait and retry |
+| 1004 | Auth failed | Check API key |
+| 1008 | Insufficient balance | Top up account |
+| 1026 | Content flagged | Rephrase prompt/lyrics |
+| 2013 | Invalid parameters | Check prompt/lyrics length |

package/skills/frontend-dev/references/minimax-tts-guide.md

@@ -0,0 +1,78 @@
+# TTS Guide
+
+## CLI usage (recommended)
+
+```bash
+# Basic
+python scripts/minimax_tts.py "Hello world" -o output.mp3
+
+# Custom voice and speed
+python scripts/minimax_tts.py "你好世界" -o hi.mp3 -v female-shaonv --speed 0.9
+
+# WAV format, high quality
+python scripts/minimax_tts.py "Welcome" -o out.wav -v male-qn-jingying --format wav --sample-rate 32000
+
+# With emotion (for speech-2.6 models)
+python scripts/minimax_tts.py "Great news!" -o happy.mp3 -v female-shaonv --emotion happy --model speech-2.6-hd
+```
+
+## Programmatic usage
+
+```python
+from minimax_tts import tts
+
+# Basic
+audio_bytes = tts("Hello world")
+
+# With options
+audio_bytes = tts(
+    text="Welcome to our product.",
+    voice_id="female-shaonv",
+    model="speech-2.8-hd",
+    speed=0.9,
+    fmt="mp3",
+)
+
+# Save to file
+with open("output.mp3", "wb") as f:
+    f.write(audio_bytes)
+```
+
+## Limits
+
+- **Sync TTS:** max 10,000 characters per request
+- **Pause markers:** insert `<#1.5#>` for a 1.5s pause (range: 0.01–99.99s)
+
+## Model selection
+
+| Model | Best for |
+|-------|----------|
+| `speech-2.8-hd` | Highest quality, auto emotion (recommended) |
+| `speech-2.8-turbo` | Fast, good quality |
+| `speech-2.6-hd` | Manual emotion control needed |
+| `speech-2.6-turbo` | Fast + manual emotion |
+
+## Voice selection
+
+See [minimax-voice-catalog.md](minimax-voice-catalog.md) for the full list.
+
+Common voices:
+
+| Voice ID | Gender | Style |
+|----------|--------|-------|
+| `male-qn-qingse` | Male | Young, gentle |
+| `male-qn-jingying` | Male | Elite, authoritative |
+| `male-qn-badao` | Male | Dominant, powerful |
+| `female-shaonv` | Female | Young, bright |
+| `female-yujie` | Female | Mature, elegant |
+| `female-chengshu` | Female | Sophisticated |
+| `presenter_male` | Male | News presenter |
+| `presenter_female` | Female | News presenter |
+| `audiobook_male_1` | Male | Audiobook narrator |
+| `audiobook_female_1` | Female | Audiobook narrator |
+
+## Best practices
+
+- Use `speech-2.8-hd` and let emotion auto-match — don't manually set emotion unless needed
+- Use 32000 sample rate for web audio (good balance of quality and file size)
+- For long text (>10,000 chars), split into chunks and merge with FFmpeg