User Guide

User Guide

Complete guide to using Hiro UST Generator.

⚠️ Windows Only • Recommended: OpenUtau (most stable output)

Getting Started

1. Launch the Application

python scripts/hiro_ust_dev.py

The main window will open with the song editor.

2. Enter Your Lyrics

In the 🎵 Song Lyrics section, enter Japanese lyrics in any of these formats:

• Hiragana: きゃっきゃ
• Katakana: キャッキャ
• Romaji: kyakkya

You can organize lyrics into sections:

[Verse 1]
きゃっきゃ うれし いたい

[Chorus]
いたみ いたみ きもちいい

[Verse 2]
ゆびさき きりさけ

3. Configure Settings

⏱️ Timing

• Tempo (BPM): 60-240 beats per minute
• Base Length: 240 ticks (default, ≈ quarter note)
• Line Pause: Silence between lines (ticks)
• Section Pause: Silence between sections (ticks)

🎤 Voice

• Voice: Soprano, Alto, Tenor, Bass (sets key range)
• Scale: Musical scale for melody (Major, Minor, Pentatonic, etc.)
• Length Variation: 0.0-1.0 (randomness in note duration)
• Stretch Probability: 0.0-1.0 (likelihood of extending vowels)

🎵 Melody Modes

• 🎼 Motif Memory: Remember pitch patterns from previous notes
• 🎭 Lyrical Mode: Smart melody generation based on text
• 🎹 Monotone (Flat): All notes at same pitch
• ♯ Microtones (Qt): Enable quarter-tone notes
• 🎸 I-IV-V Chords: Chord-based melody generation
• Intone: How strictly to follow the scale (Tight, Medium, Wide, Wild)
• Accent: Japanese pitch accent pattern (None, Heiban, Atamadaka, Nakadaka, Odaka)
• Curve: Melodic contour bias (-50 to +50)
• Range: Pitch range in semitones (40-120)

⚙️ Output

• Pre-Utterance (P): Lead-in time in milliseconds
• Voice Overlap (O): Overlap with previous note
• Intensity (I): Base volume (0-200)
• Envelope (E): Pitch envelope preset
• Seed (S): Random seed for reproducibility (same seed = same results)
• 🌟 USTX Mode: Save as USTX format (OpenUtau) instead of UST

4. Generate

Click 🎵 Gen to create the UST file in memory.

The status bar shows progress.

5. Preview

Click 👀 Preview to hear the phonemes without generating a full file.

6. Save

Click 💾 Save to save the generated UST/USTX file to disk.

---

Features Explained

Accent Patterns

Japanese has pitch accent that varies by word:

• Heiban (平板): Flat pronunciation (neutral)

  • Example: "ニッポン"

• Atamadaka (頭高): High on first mora, then low

  • Example: "トウキョウ"

• Nakadaka (中高): Low then high, then drop

  • Example: "サクラ"

• Odaka (尾高): Low then high on last mora

  • Example: "ハナ"

Voice Selection

Each voice has a different key range:

Voice	Key	Range	Best For
Soprano	84	Highest	Bright, high-pitched voices
Alto	72	Mid-high	Standard female voices
Tenor	60	Mid-low	Standard male voices
Bass	48	Lowest	Deep male voices

Scales

Available musical scales:

• Major: 1-2-3-5-6-8-12 (bright, happy)
• Minor: 1-2-3-5-6-8-10 (dark, sad)
• Major Pentatonic: 1-2-3-5-6 (simple, folk-like)
• Minor Pentatonic: 1-3-5-7-10 (bluesy, mysterious)
• Dorian: Modal scale (jazzy)
• Blues: Special blues scale
• Whole Tone: Chromatic, experimental

Envelope Presets

Different vocal characteristics:

• Pop: Balanced, modern sound
• Rock: Punchy, aggressive
• Opera: Classical, extended sustain
• Breathy: Soft, airy
• Belt: Loud, powerful
• Whisper: Quiet, intimate
• Vibrato: With natural vibration

---

Workflow Example

Creating a Simple Song

1. Enter lyrics:

   [Verse]
   きれい な そら
   

2. Configure:

   • Voice: Alto
   • Scale: Major Pentatonic
   • Tempo: 120 BPM

3. Generate:

   • Click "🎵 Gen"

4. Save:

   • Click "💾 Save"
   • Choose location and filename
   • Format: UST or USTX

5. Use in UTAU:

   • Open UTAU
   • Import the UST file
   • Assign voice bank
   • Render

Advanced: With Accents

1. Enter lyrics with clear word boundaries:

   [Verse]
   きょう こんにちは
   

2. Set Accent: "Atamadaka" (standard greeting pattern)

3. Configure other settings as usual

4. Generate and save

---

Tips & Tricks

Get Natural-Sounding Results

1. Use Motif Memory: Keeps similar pitch patterns between notes
2. Set Lyrical Mode: Intelligent melody based on text structure
3. Choose Appropriate Intone:
   • Tight: More staccato
   • Medium: Balanced (recommended)
   • Wide: More legato
   • Wild: Very expressive

Randomness Control

1. Use Seed: Set same seed to get identical results
2. Randomize: Click 🎲 button to generate new seed
3. Length Variation: 0.0 = fixed length, 1.0 = maximum variation

Testing Different Settings

Use the 🎲 Randomize Seed button to quickly try variations:

1. Set your preferred parameters
2. Click the seed button repeatedly
3. Check preview to hear different melodies
4. Save the one you like best

---

Keyboard Shortcuts

Action	Shortcut
Generate	Ctrl+G
Save	Ctrl+S
Preview	Ctrl+P
Clear Input	Ctrl+A then Delete

---

Output Formats

UST Format

• Pros: Wide compatibility, standard format
• Cons: Limited features, character encoding issues
• Note: ⚠️ May produce Chinese characters in UTAU (use OpenUtau instead)
• Use: Only if OpenUtau unavailable

USTX Format

• Pros: More features, OpenUtau support, stable output
• Cons: Newer format
• Recommended: ✅ Best option (use with OpenUtau)
• Use: Default choice for best results

✅ OpenUtau (Recommended)

• Cross-platform: Windows, macOS, Linux
• Stable output: No character encoding issues
• Modern format: Full USTX support
• Best compatibility: Recommended for all users
• Download: OpenUtau

Recommendation: Use USTX format + OpenUtau for best results!

---

FAQ

Q: Why are some notes at weird pitches?
A: This is intentional! The melody generator uses the scale and voice characteristics to create natural-sounding melodic contours.

Q: How do I use presets?
A: Save your current settings with "💾 Save Preset", then load them later with "📂 Load Preset"

Q: Can I edit the generated UST?
A: Yes! Generate UST files are standard format. Edit them in UTAU as normal.

Q: What does "Pre-Utterance" do?
A: It's the lead-in time before the note starts. Adjust for smoother transitions.

See FAQ for more questions.

---

Troubleshooting

Issue: Generated UST sounds robotic

• Solution: Enable "Lyrical Mode" and "Motif Memory" for more natural results

Issue: Notes are too high/low

• Solution: Change the "Voice" setting to adjust key range

Issue: Accents don't sound right

• Solution: Experiment with different accent patterns or set to "None" for neutral

Issue: Phonemes preview doesn't work

• Solution: Check phoneme mode is set correctly (Japanese recommended)

---

Next Steps

• Usage Examples - Code examples
• Architecture - Technical details
• FAQ - Common questions