# lib/

This directory contains external API clients and utilities for Suno Spaces.

## Files

### `sunoClient.ts`

Simplified client for interacting with Suno's internal APIs to generate songs.

**Key Features:**
- Generate songs using `/api/generate/v2-web` endpoint (generates 2 songs per request)
- Check song status using `/api/feed/v3` endpoint (supports multiple IDs via `?ids=` query param)
- Poll for completion with configurable intervals
- Clean TypeScript types for all API interactions

**Important API Parameter Usage:**

- **`prompt`**: Contains **actual lyrics** - the literal text that will be sung in the song (not a description of what to generate)
- **`tags`**: Contains **genre/style descriptors** as comma-separated string (e.g., "lofi, chill, jazz", "indie rock, energetic")
- **`mv`**: Set to `"chirp-crow"` (the model version) - automatically added by client

**Note for Orphy Assistant:**
When users request songs without providing lyrics, Orphy generates original lyrics based on their theme/topic and passes those generated lyrics into the `prompt` field. The `tags` field contains the musical style/genre information.

**Lyrics must be formatted with section tags:**
```
[Verse]
Walking down the street at midnight
City lights reflecting in my eyes

[PreChorus]
Something's changing, I can feel it

[Chorus]
This is where we come alive
Dancing under neon skies

[Verse 2]
Empty cafes, quiet conversations
...
```

**Guidelines:**
- Use [Verse], [Chorus], [PreChorus], [Bridge], [Outro] tags
- Structure: Verse → PreChorus → Chorus, then repeat
- Make choruses catchy and memorable
- Avoid excessive rhyming - natural flow is better

**Usage in Convex:**

```typescript
import { createSunoClient } from '../lib/sunoClient';

// In a Convex action (actions have access to environment variables)
export const generateSong = action({
  args: {
    prompt: v.string(),  // Actual lyrics to be sung
    tags: v.optional(v.string()),  // Genre/style tags
  },
  handler: async (ctx, args) => {
    const client = createSunoClient();

    // Generate 2 songs
    const songIds = await client.generateSongs({
      prompt: args.prompt,  // e.g., "Verse 1: Walking down the street..."
      tags: args.tags,  // e.g., "indie rock, energetic, 2000s"
      makeInstrumental: false,
    });

    // Poll for completion
    const songs = await client.waitForCompletion(songIds);

    return songs;
  },
});
```

**Environment Variables:**

Set these in your Convex dashboard (https://dashboard.convex.dev):
- `SUNO_BASE_URL`: Base URL for Suno API (e.g., `https://studio-api.suno.ai`)
- `SUNO_SESSION_TOKEN`: Long-lived session token for authentication

See `convex/.env.example` for template.

**API Reference:**

- **`generateSongs(request)`**: Generate 2 songs from a prompt
  - Params:
    - `prompt`: string - Lyrics/text content for the song
    - `tags`: string (optional) - Comma-separated genre/style tags
    - `makeInstrumental`: boolean (optional) - Generate instrumental version
    - `waitAudio`: boolean (optional) - Wait for audio to be ready
  - Returns: `string[]` - Array of song IDs
  - Note: Automatically sets `mv: "chirp-crow"` model version

- **`getSongStatus(songIds)`**: Check status of multiple songs
  - Returns: `SongMetadata[]` - Array of song metadata with status

- **`waitForCompletion(songIds, options?)`**: Poll until songs complete
  - Returns: `SongMetadata[]` - Final song metadata
  - Options: `maxAttempts` (default: 150), `pollIntervalMs` (default: 2000)

**Song Status Flow:**
1. `pending`: Song generation queued
2. `processing`: Song being generated
3. `completed`: Song ready with audio/video URLs
4. `failed`: Generation failed (check `errorMessage`)