Skill: ivangdavila/udio (version 1.0.0)

--- name: Udio slug: udio version: 1.0.0 homepage: https://clawic.com/skills/udio description: Generate AI music with Udio via API wrappers or browser automation, with prompt engineering and song extensions. metadata: {"clawdbot":{"emoji":"🎵","requires":{"bins":["python3"],"env":["UDIO_AUTH_TOKEN"]},"primaryEnv":"UDIO_AUTH_TOKEN","os":["linux","darwin","win32"]}} --- ## Setup On first use, read `setup.md` for integration guidelines. ## When to Use User wants to generate music with Udio. Agent can use API wrappers for programmatic generation, browser automation for direct platform interaction, or guide prompt engineering. ## Architecture Memory at `~/udio/`. See `memory-template.md` for structure. ``` ~/udio/ ├── [memory.md] # Created on first use: preferences, auth token location ├── [projects/] # Per-project song tracking └── [songs/] # Downloaded audio files ``` ## Quick Reference | Topic | File | |-------|------| | Setup | `setup.md` | | Memory | `memory-template.md` | | API usage | `api.md` | | Browser automation | `browser.md` | | Prompt crafting | `prompts.md` | | Style tags | `styles.md` | | Lyrics guide | `lyrics.md` | ## Core Rules ### 1. Choose the Right Approach | Situation | Method | |-----------|--------| | Programmatic generation, batch jobs | API wrapper | | User wants to browse and listen | Browser automation | | Just need prompt help | Prompt engineering only | ### 2. API Requires Auth Token Udio has no official public API. Community wrappers use the internal API: - Token: `sb-api-auth-token` cookie from udio.com - Token expires: refresh if 401 errors occur - See `api.md` for setup instructions ### 3. Structure Prompts in Layers ``` [genre] [subgenre] [mood] [instruments] [voice] [era/influence] ``` Example: "indie folk melancholic acoustic guitar female vocals 90s" ### 4. Extend Songs Strategically Udio generates ~30 second clips. Build full songs: 1. Create initial clip with strong hook 2. Extend 2-3 times with consistent style 3. Add outro with ending indicators 4. Target 2-4 minutes total ### 5. Save Successful Seeds Same prompt + different seed = different result. When close to desired output: - Note the seed number - Try adjacent seeds (seed +/- 1) - Document working combinations ## API Integration ### Python Wrapper (Recommended) ```bash pip install udio_wrapper ``` ```python from udio_wrapper import UdioWrapper # Initialize with auth token udio = UdioWrapper("your-sb-api-auth-token") # Create a song song = udio.create_song( prompt="electronic ambient downtempo dreamy synth pads", seed=-1, # -1 for random custom_lyrics="Optional lyrics here" ) # Extend the song extended = udio.extend( prompt="add drums and bass, building energy", audio_conditioning_path=song['song_path'], audio_conditioning_song_id=song['id'] ) # Add outro outro = udio.add_outro( prompt="gentle fade out, conclusion", audio_conditioning_path=extended['song_path'], audio_conditioning_song_id=extended['id'] ) ``` ### TypeScript/Node Wrapper ```bash npm install udio-wrapper ``` ```typescript import { createUdioWrapper } from 'udio-wrapper'; const client = await createUdioWrapper('your-auth-token'); const song = await client.createSong({ prompt: 'indie rock upbeat energetic guitar', seed: 12345, customLyrics: 'Optional lyrics' }); const completed = await client.waitForCompletion(song.id); console.log('Download URL:', completed.url); ``` ### Complete Song Sequence ```python # Generate intro + extensions + outro in one call complete = udio.create_complete_song( short_prompt="peaceful acoustic guitar melody", extend_prompts=[ "add piano and soft strings", "introduce light percussion, building" ], outro_prompt="gentle resolution, fading", num_extensions=2, custom_lyrics_short="Opening verse...", custom_lyrics_extend=["Middle section...", "Bridge..."], custom_lyrics_outro="Final words..." ) ``` ## Browser Automation When API isn't available or user prefers visual interaction: ### Navigate to Udio ``` browser action=open targetUrl="https://www.udio.com" profile=openclaw ``` ### Get Auth Token (for API use) 1. Open DevTools: `Cmd+Option+I` (Mac) or `F12` (Windows) 2. Go to Application tab > Cookies > udio.com 3. Find `sb-api-auth-token` 4. Copy the value ### Generate Music via UI 1. Navigate to create page 2. Enter prompt in text field 3. Adjust settings (instrumental, duration) 4. Click generate 5. Wait for completion (~30-60 seconds) 6. Download or extend ## Prompt Patterns ### By Genre | Genre | Prompt Pattern | |-------|---------------| | Electronic | `electronic [subgenre] [mood] synth [texture] [era]` | | Rock | `[sub]rock [energy] [guitars] [drums] [vocals] [decade]` | | Hip Hop | `hip hop [subgenre] [beat style] [sample type] [era]` | | Jazz | `jazz [subgenre] [instruments] [setting] [mood]` | | Classical | `classical [period] [ensemble] [mood] [dynamics]` | ### Mood Combinations | Energy | Mood Stack | |--------|------------| | High + Positive | euphoric energetic uplifting triumphant | | Low + Positive | peaceful calm serene contemplative | | High + Negative | aggressive chaotic intense dark | | Low + Negative | melancholic somber mournful introspective | | Complex | bittersweet nostalgic hopeful yearning | ### Voice Control ``` # Female vocals female vocals ethereal soprano breathy # Male vocals male vocals deep baritone raspy emotional # Choir choir harmonies gospel powerful anthemic # No vocals instrumental only no singing no vocals ``` ## Common Traps | Trap | Problem | Solution | |------|---------|----------| | Vague prompts | "good music" = random | Be specific: genre, mood, instruments | | Contradictions | "upbeat sad" confuses model | Pick consistent descriptors | | Token expiry | 401 errors | Re-extract from browser cookies | | Too many keywords | 20+ terms dilute focus | Use 5-10 key descriptors | | No seed tracking | Can't reproduce good results | Log seeds for successful generations | | Abrupt extensions | Jarring transitions | Match style/key in extend prompts | ## Extension Strategy ### Building Full Tracks | Phase | Duration | Prompt Additions | |-------|----------|------------------| | Intro | 0-30s | "intro, building, atmospheric" | | Verse/Main | 30s-2m | Original prompt | | Bridge | 2m-2:30 | "variation, bridge, key change" | | Outro | Final 30s | "outro, ending, fade, resolution" | ### Ending Indicators Add to final extend/outro: - "fade out" / "fading" - "song ending" / "conclusion" - "final chorus" / "last verse" - "resolution" / "outro" ## Data Storage This skill creates `~/udio/` on first use: - **memory file** — Preferences, successful prompts, token location reference - **projects folder** — Per-project tracking with seeds and URLs - **songs folder** — Downloaded audio files (optional) All data stays local. Auth tokens should be stored in system keychain, not plain text. ## Scope **This skill does:** - Generate music via community API wrappers (requires auth token) - Navigate udio.com with browser automation (user must be logged in) - Craft optimized prompts for Udio's model (no token needed) - Track projects, seeds, and successful patterns locally - Download generated audio files to `~/udio/songs/` **This skill does NOT:** - Store auth tokens in plain text (must use keychain/credential manager) - Bypass Udio's rate limits or terms of service - Access files outside `~/udio/` - Auto-extract tokens without user guidance ## Security Notes **Auth Token:** The `sb-api-auth-token` cookie grants API access to your Udio account. Handle it like a password: - Store in system keychain, never in plain text - Token expires after ~7 days of inactivity - Re-extract if you get 401 errors **Community Wrappers:** The Python and Node wrappers are community-maintained (not official Udio software). Review their source code before installing: - Python: github.com/flowese/UdioWrapper - Node: github.com/josephgodwinkimani/udio-wrapper **Prompt-Only Mode:** If you prefer not to use API or share tokens, this skill works in prompt-only mode — just help with crafting effective prompts without any API calls. ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | api.udio.com | Prompts, lyrics | Music generation (via wrappers) | | udio.com | Browser session | Direct platform access | Auth token is sent with API requests. No other data leaves the machine. ## Trust By using this skill with API wrappers, prompts and lyrics are sent to Udio's servers for music generation. Only use if you trust Udio with your creative content. Review Udio's terms of service at udio.com/terms. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `audio` — Audio processing and editing - `video` — Combine music with video content - `ffmpeg` — Audio format conversion ## Feedback - If useful: `clawhub star udio` - Stay updated: `clawhub sync`

path: api.md
content: # API Reference — Udio

Udio has no official public API. Community wrappers interact with the internal API.

## Available Wrappers

| Wrapper | Language | Install | Repo |
|---------|----------|---------|------|
| udio_wrapper | Python | `pip install udio_wrapper` | github.com/flowese/UdioWrapper |
| udio-wrapper | TypeScript | `npm install udio-wrapper` | github.com/josephgodwinkimani/udio-wrapper |

## Getting the Auth Token

The wrappers require `sb-api-auth-token` from your browser session.

### Steps
1. Go to [udio.com](https://www.udio.com) and log in
2. Open DevTools:
   - **Chrome/Edge:** `Ctrl+Shift+I` (Windows) or `Cmd+Option+I` (Mac)
   - **Firefox:** `Ctrl+Shift+I` or `F12`
3. Navigate to **Application** tab (Chrome) or **Storage** tab (Firefox)
4. Click **Cookies** > **https://www.udio.com**
5. Find `sb-api-auth-token`
6. Copy the **Value** (long string starting with `base64-...`)

### Token Handling
```python
# GOOD: Use environment variable
import os
auth_token = os.getenv('UDIO_AUTH_TOKEN')

# GOOD: Use keychain (macOS)
# security add-generic-password -a udio -s udio_auth_token -w "token-value"
# security find-generic-password -a udio -s udio_auth_token -w
```

**Never store tokens in plain text files or commit to git.**

### Token Expiration
Tokens expire after ~7 days of inactivity. If you get 401 errors:
1. Log into udio.com again
2. Re-extract the token from cookies
3. Update your environment variable

## Python Wrapper (udio_wrapper)

### Installation
```bash
pip install udio_wrapper
# or from source
pip install git+https://github.com/flowese/UdioWrapper.git
```

### Basic Usage
```python
from udio_wrapper import UdioWrapper

udio = UdioWrapper(auth_token)

# Create a song (~30 seconds)
result = udio.create_song(
    prompt="electronic ambient chill downtempo synth pads warm",
    seed=-1,  # -1 = random seed
    custom_lyrics=None  # Optional
)

print(f"Song ID: {result['id']}")
print(f"Audio URL: {result['song_path']}")
```

### Extend a Song
```python
# Extend the first clip to ~1 minute
extended = udio.extend(
    prompt="add subtle drums and bass, maintain atmosphere",
    seed=-1,
    audio_conditioning_path=result['song_path'],
    audio_conditioning_song_id=result['id'],
    custom_lyrics=None
)
```

### Add Outro
```python
# Add ending section
outro = udio.add_outro(
    prompt="gentle fade out, peaceful resolution",
    seed=-1,
    audio_conditioning_path=extended['song_path'],
    audio_conditioning_song_id=extended['id'],
    custom_lyrics="Final words fade away..."
)
```

### Complete Song Sequence
Generate intro + extensions + outro in one call:
```python
complete = udio.create_complete_song(
    short_prompt="acoustic guitar fingerpicking peaceful morning",
    extend_prompts=[
        "add soft piano accompaniment",
        "introduce gentle strings, building emotion"
    ],
    outro_prompt="peaceful resolution, fading into silence",
    num_extensions=2,
    custom_lyrics_short="The sun rises...",
    custom_lyrics_extend=[
        "A new day begins...",
        "Hope fills the air..."
    ],
    custom_lyrics_outro="And so it ends..."
)

# Returns list of all generated segments with URLs
for segment in complete:
    print(f"{segment['type']}: {segment['song_path']}")
```

### Parameters Reference

| Parameter | Type | Description |
|-----------|------|-------------|
| `prompt` | str | Music description (genre, mood, instruments) |
| `seed` | int | Reproducibility seed. -1 = random |
| `custom_lyrics` | str | Optional lyrics to include |
| `audio_conditioning_path` | str | URL of song to extend |
| `audio_conditioning_song_id` | str | ID of song to extend |

## TypeScript/Node Wrapper (udio-wrapper)

### Installation
```bash
npm install udio-wrapper
```

### Node.js Usage
```typescript
import { createUdioWrapper } from 'udio-wrapper/node';

async function generateMusic() {
    const client = await createUdioWrapper(process.env.UDIO_AUTH_TOKEN);
    
    // Create song
    const song = await client.createSong({
        prompt: 'indie rock upbeat energetic electric guitar',
        seed: 12345,
        customLyrics: 'Optional lyrics here'
    });
    
    console.log('Song created:', song.id);
    
    // Wait for completion
    const completed = await client.waitForCompletion(song.id, {
        pollingInterval: 3000,  // Check every 3 seconds
        maxAttempts: 30,        // Max 30 attempts
        onProgress: (status) => {
            console.log(`Status: ${status.status}`);
        }
    });
    
    console.log('Download URL:', completed.url);
}
```

### Browser Usage
```typescript
import { createUdioWrapper } from 'udio-wrapper/browser';

const client = createUdioWrapper(authToken);
// Same API as Node.js
```

### Extend Song
```typescript
const extended = await client.extendSong({
    prompt: 'add drums and build energy',
    audioConditioningPath: song.url,
    audioConditioningSongId: song.id,
    customLyrics: 'The beat drops...'
});
```

### Complete Sequence
```typescript
const sequence = await client.createCompleteSequence({
    shortPrompt: 'peaceful piano melody',
    extendPrompts: [
        'add strings',
        'introduce soft percussion'
    ],
    outroPrompt: 'gentle fade to silence',
    numExtensions: 2,
    customLyricsShort: 'Opening...',
    customLyricsExtend: ['Middle...', 'Bridge...'],
    customLyricsOutro: 'The end...'
});
```

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| 401 Unauthorized | Token expired or invalid | Re-extract from browser |
| 429 Rate Limited | Too many requests | Wait and retry |
| 500 Server Error | Udio service issue | Retry later |
| Timeout | Generation taking too long | Increase timeout, retry |

```python
from udio_wrapper import UdioWrapper
import time

def generate_with_retry(udio, prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return udio.create_song(prompt=prompt)
        except Exception as e:
            if "401" in str(e):
                raise Exception("Token expired - re-extract from browser")
            if "429" in str(e):
                wait = 60 * (attempt + 1)
                print(f"Rate limited, waiting {wait}s...")
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")
```

## Response Structure

### Create Song Response
```json
{
    "id": "song_abc123",
    "status": "processing",
    "song_path": "https://...",
    "created_at": "2024-01-15T10:30:00Z"
}
```

### Completed Song
```json
{
    "id": "song_abc123",
    "status": "completed",
    "song_path": "https://cdn.udio.com/songs/abc123.mp3",
    "duration": 32.5,
    "seed": 12345
}
```

## Rate Limits

Udio has undocumented rate limits:
- Free tier: ~10 generations/day
- Paid tiers: Higher limits based on plan
- Respect rate limits to avoid account restrictions

## Disclaimer

These wrappers are community-maintained and not officially supported by Udio. The internal API may change without notice. Use at your own risk and respect Udio's terms of service.


path: browser.md
content: # Browser Automation — Udio

Use browser automation when API wrappers aren't available or user prefers visual interaction.

## Prerequisites

- Browser tool available (openclaw profile)
- User has Udio account (free tier works)

## Opening Udio

```
browser action=open targetUrl="https://www.udio.com" profile=openclaw
```

Wait for page load, then take snapshot:
```
browser action=snapshot profile=openclaw
```

## Authentication

### Check Login Status
After snapshot, look for:
- "Sign In" or "Log In" button = not logged in
- User avatar/profile = logged in
- "Create" button visible = logged in

### Login Flow
If not logged in:
1. Click "Sign In" button
2. User completes OAuth (Google/Discord/etc.)
3. Wait for redirect back to udio.com
4. Verify logged in via snapshot

```
browser action=act request={"kind":"click","ref":"Sign In button ref"} profile=openclaw
```

Note: OAuth requires user interaction. Pause and wait for user to complete.

## Creating Music

### Navigate to Create Page
```
browser action=navigate targetUrl="https://www.udio.com/create" profile=openclaw
```

### Enter Prompt
1. Take snapshot to find prompt input field
2. Type prompt into the field:
```
browser action=act request={"kind":"type","ref":"prompt input ref","text":"electronic ambient chill synth pads warm analog"} profile=openclaw
```

### Configure Options

**Instrumental Only:**
Look for "Instrumental" toggle or checkbox and enable if needed.

**Custom Lyrics:**
If lyrics input is available, enter formatted lyrics:
```
[Verse 1]
Your lyrics here

[Chorus]
Hook goes here
```

### Generate
Click the "Create" or "Generate" button:
```
browser action=act request={"kind":"click","ref":"create button ref"} profile=openclaw
```

### Wait for Generation
Generation takes 30-60 seconds. Monitor progress:
1. Take periodic snapshots
2. Look for progress indicator
3. Wait for audio player to appear

```
# Check every 10 seconds
browser action=snapshot profile=openclaw
# Look for completed song or progress percentage
```

## Extending Songs

### From Song Page
1. Navigate to a generated song
2. Look for "Extend" or "Continue" button
3. Enter extension prompt
4. Click extend

### Extension Prompts
When extending, describe what to add:
- "add drums and build energy"
- "introduce strings, more emotional"
- "transition to chorus, powerful"

## Downloading Songs

### Find Download Button
After generation completes:
1. Look for download icon (usually arrow down)
2. Or right-click on audio player
3. Click download

### Save Location
Downloaded files typically go to browser's default download folder.
Move to `~/udio/songs/` for organization.

## Extracting Auth Token

For API wrapper usage, extract the auth token from browser:

### Via Browser Console
1. Open DevTools (F12 or Cmd+Option+I)
2. Go to Console tab
3. Run:
```javascript
document.cookie.split('; ').find(c => c.startsWith('sb-api-auth-token=')).split('=')[1]
```

### Via Application Tab
1. DevTools > Application tab
2. Cookies > https://www.udio.com
3. Find `sb-api-auth-token`
4. Copy the Value

### Store Securely
```bash
# macOS Keychain
security add-generic-password -a udio -s udio_auth_token -w "paste-token-here" -U

# Retrieve later
security find-generic-password -a udio -s udio_auth_token -w
```

## Common UI Elements

| Element | Purpose | Typical Location |
|---------|---------|------------------|
| Create/Generate button | Start generation | Top nav or main page |
| Prompt input | Enter music description | Create page, center |
| Instrumental toggle | Disable vocals | Below prompt |
| Lyrics input | Custom lyrics | Below prompt (if enabled) |
| Extend button | Continue a song | Song page, below player |
| Download button | Save audio file | Song page, player controls |
| My Songs/Library | View past generations | User menu or nav |

## Handling Issues

### Page Not Loading
```
browser action=navigate targetUrl="https://www.udio.com" profile=openclaw
# Wait longer
browser action=snapshot profile=openclaw
```

### Session Expired
If actions fail or get redirected to login:
1. User needs to log in again
2. May need to re-extract auth token

### Generation Stuck
If generation takes >2 minutes:
1. Check for error messages in snapshot
2. May need to refresh and retry
3. Udio servers may be overloaded

### Rate Limited
Free tier has daily limits. If hitting limits:
1. Wait for daily reset
2. Consider paid plan
3. Use API wrapper for better error handling

## Workflow Example

Complete workflow for generating a song:

```python
# 1. Open Udio
browser.open("https://www.udio.com/create")
snapshot = browser.snapshot()

# 2. Check if logged in
if "Sign In" in snapshot:
    print("Please log in to Udio...")
    # Wait for user
    
# 3. Enter prompt
browser.type(prompt_ref, "indie rock upbeat guitar drums energetic")

# 4. Enable instrumental if needed
if instrumental:
    browser.click(instrumental_toggle_ref)

# 5. Generate
browser.click(create_button_ref)

# 6. Wait for completion
while True:
    snapshot = browser.snapshot()
    if "completed" in snapshot or audio_player_visible:
        break
    time.sleep(10)

# 7. Download
browser.click(download_button_ref)
print("Song downloaded!")
```

## Tips

- **Take frequent snapshots** — UI changes during generation
- **Be patient** — Generation takes 30-60+ seconds
- **Save working sessions** — Browser profile preserves login
- **Note successful prompts** — Track what works for future use
- **Watch for rate limits** — Free tier is limited


path: lyrics.md
content: # Lyrics Guide — Udio

How to write and format lyrics for optimal Udio generation.

## Section Tags

Udio recognizes structural tags that guide song arrangement:

| Tag | Purpose | Typical Length |
|-----|---------|----------------|
| `[Intro]` | Opening, often instrumental | 4-8 bars |
| `[Verse]` | Story/narrative content | 8-16 bars |
| `[Verse 1]`, `[Verse 2]` | Numbered verses | 8-16 bars |
| `[Pre-Chorus]` | Build before chorus | 4-8 bars |
| `[Chorus]` | Hook, memorable | 8-16 bars |
| `[Bridge]` | Contrast section | 4-8 bars |
| `[Outro]` | Ending section | 4-8 bars |
| `[Instrumental]` | No vocals | Variable |
| `[Break]` | Stripped down moment | 4-8 bars |
| `[Drop]` | Electronic music climax | 8-16 bars |

## Basic Song Structure

### Pop/Rock Standard
```
[Intro]

[Verse 1]
First verse lyrics here
Second line of verse
Third line continues
Fourth line wraps up

[Chorus]
Catchy hook repeated
Main message here
Memorable and singable
Hook again

[Verse 2]
Story continues here
Building on verse one
New details emerge
Leading to chorus

[Chorus]
Catchy hook repeated
Main message here
Memorable and singable
Hook again

[Bridge]
Different perspective
Change in melody
Building tension
Back to chorus

[Chorus]
Catchy hook repeated
Main message here
Final emotional peak
Resolution

[Outro]
```

### Electronic/Dance
```
[Intro]

[Build]
Tension rising here
Energy increasing

[Drop]
[Instrumental]

[Breakdown]
Stripped back moment
Breathe before next drop

[Build]
Rising again
Here it comes

[Drop]
[Instrumental]

[Outro]
```

### Ballad
```
[Intro]
[Instrumental]

[Verse 1]
Slow emotional opening
Setting the scene
Personal and intimate
Drawing listener in

[Chorus]
Emotional core revealed
Main theme expressed
Powerful and moving
Heart of the song

[Verse 2]
Story deepens here
More vulnerability
Building to climax
Emotional stakes rise

[Chorus]
Emotional core revealed
Main theme expressed
Even more powerful
Building intensity

[Bridge]
Breaking point moment
Highest emotion
Resolution beginning
Catharsis

[Chorus]
Final statement
Resolution achieved
Peaceful or powerful
Closing sentiment

[Outro]
Gentle fade
```

## Writing Effective Lyrics

### Line Length
- **Short lines work best:** 4-8 syllables per line
- **Consistent rhythm:** Similar syllable counts across lines
- **Natural breaks:** End lines where you'd naturally pause

### Rhyme Schemes
| Scheme | Pattern | Example |
|--------|---------|---------|
| AABB | Lines 1-2 rhyme, 3-4 rhyme | day/way, night/light |
| ABAB | Alternating rhymes | day/night/way/light |
| ABCB | Only 2nd and 4th rhyme | day/night/way/light |
| Free | No strict pattern | Varies |

### Emotional Words
Words that translate well to sung emotion:
- Heart, soul, fire, rain, night, light
- Love, pain, hope, fear, dream
- Forever, never, always, away
- Fall, rise, break, heal

### Avoid
- Long compound words (hard to sing)
- Technical jargon (doesn't flow)
- Tongue twisters
- Too many syllables per line

## Vocal Direction Tags

Add in brackets to guide vocal performance:

| Tag | Effect |
|-----|--------|
| `[soft]` | Quieter, intimate |
| `[powerful]` | Belting, loud |
| `[whispered]` | Breathy, quiet |
| `[spoken]` | Spoken word |
| `[harmonies]` | Layered vocals |
| `[falsetto]` | High register |
| `[ad-lib]` | Improvised vocals |

Example:
```
[Verse 1]
[soft]
Walking through the rain alone
Memories of what we'd known

[Chorus]
[powerful]
But I won't let you go
No I won't let you go
```

## Instrumental Indicators

### No Vocals
```
[Instrumental]
```
or
```
[Instrumental Break]
```

### Solo Sections
```
[Guitar Solo]
[Piano Solo]
[Saxophone Solo]
```

### Specific Instrumental Moments
```
[Strings Swell]
[Beat Drop]
[Bass Line]
```

## Ending Lyrics

To indicate song ending:
```
[Outro]
Fading away now
Fading away
[fade out]
```

Or for definite endings:
```
[Outro]
This is where it ends
Final words
[end]
```

## Language Tips

### English (Default)
Works best. Model trained primarily on English lyrics.

### Other Languages
Include language indicator in prompt:
```
Prompt: "spanish flamenco passionate vocals"
Lyrics: Spanish text
```

Languages with good support:
- Spanish
- French
- Japanese
- Korean
- Portuguese
- German

### Phonetic Writing
For non-native languages, phonetic spelling can help:
```
[Verse]
Arigatou gozaimasu
Watashi no kokoro
```

## Common Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| Wall of text | Model can't parse structure | Add section tags |
| No line breaks | Rushed delivery | Break into short lines |
| Over-rhyming | Sounds forced | Use ABCB or free verse |
| Too many words | Crammed singing | Fewer syllables per line |
| Missing chorus | No hook | Add memorable repeated section |
| Abrupt ending | Cut off feeling | Add `[Outro]` with conclusion |


path: memory-template.md
content: # Memory Template — Udio

Create `~/udio/memory.md` with this structure:

```markdown
# Udio Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending

## Approach
method: api | browser | prompt-only
wrapper: python | node | none
token_location: keychain:udio_auth_token | env:UDIO_AUTH_TOKEN | none

## Preferences

### Genres
<!-- Primary genres they gravitate toward -->

### Voice
<!-- Male, female, instrumental, specific vocal styles -->

### Production
<!-- Lo-fi, polished, vintage, modern, etc -->

### Purpose
<!-- Content creation, personal, commercial -->

## Successful Patterns

### Prompts That Worked
<!-- Copy exact prompts that produced good results -->
| Prompt | Seed | Result |
|--------|------|--------|

### Seeds to Remember
<!-- Seed numbers associated with good generations -->

## Projects

### Active
<!-- Current music projects with settings -->

### Completed
<!-- Past projects for reference -->

## Notes
<!-- Observations about their style, what to avoid -->

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Still learning preferences | Gather info opportunistically |
| `complete` | Knows their style well | Generate confidently |
| `paused` | User said "not now" | Work with what you have |

## Approach Values

| Value | When to Use |
|-------|-------------|
| `api` | User has wrapper installed and token |
| `browser` | User prefers visual interaction or no API setup |
| `prompt-only` | User just wants help crafting prompts |

## Per-Project Tracking

For larger projects, create `~/udio/projects/{project-name}.md`:

```markdown
# {Project Name}

## Goal
<!-- What they're creating -->

## Style Profile
genre: 
mood:
tempo:
voice:

## Tracks
| # | Title | Prompt | Seed | Status | URL |
|---|-------|--------|------|--------|-----|
| 1 | Intro | ... | 12345 | done | https://... |
| 2 | Main | ... | -1 | pending | |

## Notes
<!-- Project-specific observations -->
```

## Key Principles

- **Never store auth tokens** — only reference location
- Learn preferences from behavior, don't interrogate
- Save successful prompts verbatim with seeds
- Track what they reject to avoid similar suggestions
- Organize by project for multi-song work


path: prompts.md
content: # Prompt Crafting — Udio

## Prompt Structure

The most effective Udio prompts follow a layered structure:

```
[Primary Genre] [Subgenre] [Mood 1] [Mood 2] [Instruments] [Voice] [Era/Influence]
```

### Layer Breakdown

| Layer | Purpose | Examples |
|-------|---------|----------|
| Primary Genre | Base style | electronic, rock, jazz, classical |
| Subgenre | Narrow focus | ambient, shoegaze, bebop, baroque |
| Mood | Emotional tone | melancholic, euphoric, tense |
| Instruments | Sonic palette | acoustic guitar, synths, strings |
| Voice | Vocal style | female soprano, male baritone, choir |
| Era/Influence | Reference point | 80s, vintage, modern, [Artist] style |

## Example Prompts by Genre

### Electronic
```
electronic ambient downtempo dreamy synth pads warm analog 90s IDM
```
```
techno dark industrial aggressive 808 kicks distorted synths warehouse
```
```
house deep melodic progressive female vocals ethereal sunset vibes
```

### Rock
```
indie rock shoegaze dreampop reverb guitars female vocals ethereal 90s
```
```
alternative rock grunge raw emotional male vocals distorted power chords
```
```
post-rock cinematic building crescendo instrumental atmospheric guitars
```

### Hip Hop
```
hip hop boom bap jazz samples vinyl crackle old school 90s golden era
```
```
trap dark 808s hi-hats aggressive flow modern production
```
```
lo-fi hip hop chill beats study music rain sounds nostalgic
```

### Jazz
```
jazz bebop upright bass brushed drums piano trio intimate club setting
```
```
jazz fusion electric piano rhodes funky bass 70s progressive
```
```
smooth jazz saxophone mellow late night easy listening
```

### Classical / Orchestral
```
orchestral cinematic epic strings brass percussion film score adventure
```
```
classical piano solo romantic era emotional expressive rubato
```
```
chamber music string quartet intimate baroque counterpoint
```

### Pop
```
pop upbeat catchy hooks synth pop female vocals danceable modern
```
```
indie pop quirky playful acoustic elements male vocals intimate
```
```
r&b pop smooth vocals 2000s production slick beats sensual
```

## Modifier Stacks

### Tempo Modifiers
| Slow | Medium | Fast |
|------|--------|------|
| slow, downtempo, ballad | mid-tempo, groove | upbeat, fast-paced, energetic |
| 60-80 BPM feel | 90-120 BPM feel | 130+ BPM feel |

### Mood Combinations
| Energy | Mood Stack |
|--------|------------|
| High positive | euphoric energetic uplifting triumphant |
| Low positive | peaceful calm serene contemplative |
| High negative | aggressive chaotic intense furious |
| Low negative | melancholic sad dark somber |
| Complex | bittersweet nostalgic hopeful yearning |

### Production Descriptors
| Style | Descriptors |
|-------|-------------|
| Clean | polished crisp modern professional studio |
| Raw | lo-fi tape warm analog vintage imperfect |
| Atmospheric | ambient reverb spacious ethereal floating |
| Dense | layered complex rich full wall of sound |

## Negative Prompts

While Udio doesn't have explicit negative prompts, you can steer away from unwanted elements:

**Instead of:** "no vocals"
**Use:** "instrumental only" or "no singing purely instrumental"

**Instead of:** "not loud"
**Use:** "soft quiet intimate whisper"

## Artist References

You can reference artists for style guidance:
```
in the style of [Artist Name]
[Artist Name] influence
reminiscent of [Artist Name]
```

Note: Results vary. The model interprets references broadly.

## Iteration Strategy

### When Result is Close
1. Keep the working prompt structure
2. Swap one element (mood OR instrument OR voice)
3. Try 3-5 seeds with each variation

### When Result is Wrong
1. Identify what's off (genre, mood, tempo, voice)
2. Strengthen the correct elements
3. Add explicit counter-descriptors

### Example Iteration
```
Original: indie rock dreamy guitars
Problem: Too aggressive

Iteration 1: indie rock dreamy soft guitars gentle
Iteration 2: indie pop dreamy acoustic warm intimate
Iteration 3: dream pop ethereal floating shimmering guitars whispered
```


path: setup.md
content: # Setup — Udio

Read this when `~/udio/` doesn't exist or is empty. Start naturally without mentioning setup files.

## Your Attitude

You're helping someone create music with AI. Be enthusiastic about their creative vision and help them choose the best approach — API for automation, browser for visual control, or just prompt guidance.

## Priority Order

### 1. First: Integration & Approach

Within the first exchanges, understand how they want to work:

**For integration:**
- "Should this activate whenever you mention making music, or only when you specifically ask about Udio?"
- "Want me to suggest improvements proactively, or stick to what you request?"

**For approach:**
- "Do you want to use the API for programmatic generation, or prefer working through the website?"
- "Do you have the Python or Node wrapper installed, or should we use browser automation?"

Save their preference to `~/udio/memory.md`.

### 2. Then: Auth Token (if using API)

If they want API access:
1. Check if they have the auth token
2. Guide them to extract it from browser cookies
3. Help them store it securely (keychain, not plain text)

**Do not store the token in memory.md** — only note where it's stored (e.g., "keychain: udio_auth_token").

### 3. Then: Understand Their Style

Learn about their music preferences:
- What genres do they gravitate toward?
- Vocals or instrumental?
- Purpose: personal projects, content creation, commercial?
- Any reference artists or songs?

### 4. Finally: Workflow Preferences

Adapt to their level:
- **Technical:** Show code examples, explain seeds and parameters
- **Creative:** Focus on prompts and styles, handle API details quietly
- **Quick results:** Minimize questions, generate fast

## What You're Saving

In `~/udio/memory.md`:
- Preferred approach (API / browser / prompt-only)
- Token storage location (NOT the token itself)
- Favorite genres and styles
- Voice preferences
- Successful prompt patterns
- Seeds that produced good results
- Projects and their settings

## Ongoing Learning

Each session, pick up:
- New style preferences
- Prompts that worked well
- Types of generations they rejected
- Active projects and their status

## Security Note

**Never save auth tokens in plain text.** Guide users to:
- macOS: Use Keychain (`security add-generic-password`)
- Linux: Use secret-tool or encrypted file
- Windows: Use Credential Manager

Only reference where the token is stored, never the value.


path: styles.md
content: # Style Tags — Udio

Quick reference for style descriptors that Udio responds to effectively.

## Genre Tags

### Electronic
| Primary | Subgenres |
|---------|-----------|
| electronic | ambient, IDM, downtempo, chillwave |
| techno | minimal, industrial, acid, Detroit |
| house | deep house, progressive, tech house |
| trance | uplifting, psytrance, goa |
| drum and bass | liquid, jungle, neurofunk |
| dubstep | brostep, melodic dubstep, riddim |
| synthwave | retrowave, darksynth, outrun |

### Rock
| Primary | Subgenres |
|---------|-----------|
| rock | alternative, indie rock, hard rock |
| metal | heavy metal, thrash, doom, black metal |
| punk | pop punk, hardcore, post-punk |
| grunge | 90s grunge, Seattle sound |
| shoegaze | dreampop, noise pop |
| post-rock | atmospheric, cinematic |

### Hip Hop / R&B
| Primary | Subgenres |
|---------|-----------|
| hip hop | boom bap, trap, conscious |
| rap | old school, mumble, lyrical |
| r&b | neo soul, contemporary r&b |
| lo-fi | lo-fi hip hop, chillhop |

### Pop
| Primary | Subgenres |
|---------|-----------|
| pop | synth pop, electropop, art pop |
| indie pop | chamber pop, baroque pop |
| k-pop | j-pop |

### Jazz / Blues
| Primary | Subgenres |
|---------|-----------|
| jazz | bebop, cool jazz, free jazz |
| fusion | jazz fusion, jazz funk |
| blues | delta blues, Chicago blues |
| soul | motown, northern soul |

### Classical
| Primary | Subgenres |
|---------|-----------|
| classical | baroque, romantic, contemporary |
| orchestral | film score, cinematic |
| chamber | string quartet, piano solo |
| opera | aria, choral |

### World / Folk
| Primary | Subgenres |
|---------|-----------|
| folk | indie folk, traditional |
| country | americana, bluegrass |
| latin | salsa, bossa nova, reggaeton |
| world | afrobeat, celtic, middle eastern |

## Mood Tags

### Energy Level
| Low | Medium | High |
|-----|--------|------|
| calm | groovy | energetic |
| peaceful | steady | explosive |
| tranquil | flowing | intense |
| serene | relaxed | powerful |
| meditative | comfortable | driving |

### Emotional Tone
| Positive | Neutral | Negative |
|----------|---------|----------|
| happy | mysterious | sad |
| joyful | contemplative | melancholic |
| euphoric | introspective | dark |
| uplifting | thoughtful | ominous |
| triumphant | nostalgic | aggressive |
| hopeful | bittersweet | haunting |

### Atmosphere
| Light | Balanced | Heavy |
|-------|----------|-------|
| airy | warm | dense |
| bright | rich | thick |
| ethereal | full | massive |
| floating | layered | crushing |
| delicate | textured | overwhelming |

## Instrument Tags

### Strings
- acoustic guitar, electric guitar, classical guitar
- violin, viola, cello, double bass
- string quartet, string orchestra
- harp, mandolin, banjo

### Keys
- piano, grand piano, upright piano
- synthesizer, synth pads, synth leads
- organ, hammond organ, church organ
- rhodes, wurlitzer, electric piano

### Percussion
- drums, acoustic drums, electronic drums
- 808, 909, drum machine
- percussion, hand percussion
- brushes, rim shots, breakbeat

### Brass / Winds
- trumpet, saxophone, trombone
- flute, clarinet, oboe
- brass section, horn section
- orchestra winds

### Electronic
- synth bass, sub bass
- arpeggiator, sequencer
- pad, lead, pluck
- glitch, granular, modular

## Voice Tags

### Gender / Range
- male vocals, female vocals
- soprano, alto, tenor, baritone, bass
- androgynous, gender neutral

### Style
- clean vocals, raspy, breathy
- powerful, belting, whispered
- falsetto, head voice, chest voice
- spoken word, rap flow

### Treatment
- reverb vocals, dry vocals
- doubled, harmonized, choir
- processed, vocoder, autotune
- distant, intimate, close mic

### Descriptor
- emotional, passionate, detached
- smooth, rough, gritty
- ethereal, angelic, demonic
- soulful, robotic

## Production Tags

### Era
- vintage, retro, modern, futuristic
- 60s, 70s, 80s, 90s, 2000s
- classic, contemporary

### Quality
- lo-fi, hi-fi
- polished, raw, rough
- professional, bedroom production
- tape, vinyl, digital

### Space
- intimate, roomy, cavernous
- dry, wet, reverberant
- close, distant, spacious
- mono, stereo, wide

### Texture
- clean, distorted, saturated
- smooth, gritty, crunchy
- warm, cold, bright
- soft, hard, punchy

## Combination Examples

### Chill Electronic
```
electronic ambient downtempo dreamy warm lo-fi synth pads
```

### Energetic Rock
```
indie rock upbeat energetic driving electric guitar powerful drums
```

### Emotional Ballad
```
pop ballad emotional piano female vocals intimate sad powerful
```

### Dark Cinematic
```
orchestral cinematic dark ominous strings brass epic tension building
```

### Vintage Soul
```
soul motown vintage 60s warm analog smooth male vocals brass section
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)