Music Pipeline

step 1: check
  ├─ checkThreadExists
  ├─ cost = 25
  ├─ checkMusicEligibility(userId, 25)
  ├─ deductCredits(userId, 25, taskId)
  └─ { skip, startTime }

step 2: notify-processing
  └─ notifyUser({ type: "audio_status", audio: { status: "processing" } })

step 3: submit-task
  ├─ provider = getProviderByToolName(toolName)
  └─ providerTaskId = await provider.submitTask(task)

step 4: poll-result
  └─ pollWithInngestSteps(step, () => provider.pollTask(providerTaskId))
     └─ GenerationResult { success, audioUrl, ... }

step 5: post-process
  └─ processAudio(generationResult, task)   # 详见下方

step 6: finalize
  ├─ trackToolUsage + trackMediaUsage   # 仅时长，无金额
  └─ handleSuccess
     ├─ checkAudioCsam(id3CoverBuffer, lyrics, audioFileId, coverId)
     ├─ updateMusicInJsonb(taskId, { status: "completed", audioId, coverId, ... })
     └─ notifyUser({ status: "completed", url, coverUrl, ... })

1. download 音频
   ├─ fetch(audioUrl)
   └─ 按 Content-Type 推断格式（mp3/wav/ogg/flac）

2. generate cover 封面
   ├─ 优先：Suno generation result 的 cover_url
   └─ fallback：BytePlus SeedReam `seedream-5-0-260128`
      ├─ prompt: "Album cover art for a song titled '{title}'. {prompt}. Professional..."
      ├─ sharp resize 2048×2048 JPEG quality 90%
      └─ generateBlurhash (4×4 components, 32×32 resize)

3. STT + forced alignment 歌词时间戳
   ├─ KIE AI STT（音频→文本）
   ├─ ElevenLabs Scribe v2（字级时间戳）
   └─ Word[] = [{ word, start, end }, ...]
   * instrumental 曲目跳过

4. embed ID3 标签
   ├─ mp3tag.js (Bun shim)
   └─ tags:
      ├─ TIT2 (title)
      ├─ TPE1 (artist = "{nickname} via Kira Art")
      ├─ APIC (cover JPEG)
      ├─ SYLT (synced lyrics, word-level timestamps)
      └─ USLT (unsynced lyrics, full text)

5. upload 到 Supabase Storage
   ├─ audio: {userId}/{threadId}/music_{audioId}.mp3  cacheControl:3600
   └─ cover: {userId}/{threadId}/mc_{coverId}.jpg     metadata: blurhash, size

checkAudioCsam({
  id3CoverBuffer,    // 封面 JPEG
  lyrics,            // 歌词全文
  audioFileId,       // Storage 路径
  coverId,           // Storage 路径（如有）
})

Promise.all([
  detectCsamFromBuffer(id3CoverBuffer),  // coverHit
  detectCsamFromText(lyrics),            // textHit
])

命中任一 → block:
  ├─ 删除 audioFileId + coverId
  ├─ 写 failed_uploads 表
  ├─ notify { type: "audio_status", audio: { status: "failed", errorCode: "csam_blocked" } }
  └─ credits 不退款

{
  "type": "audio_status",
  "taskId": "...",
  "audio": {
    "taskId": "...",
    "status": "processing" | "completed" | "failed" | "insufficient_credits" | "insufficient_plan",
    "url": "https://...",
    "coverUrl": "https://...",
    "durationMs": 30500,
    "blurhash": "...",
    "syncedLyrics": [{ "text": "word", "start": 0.5, "end": 0.7 }, ...],
    "errorCode": "csam_blocked",
    "errorMessage": "..."
  },
  "timestamp": "2026-04-14T12:34:56Z"
}

interface Audio {
  toolCallId?: string;
  toolName?: string;
  taskId: string;
  provider: "suno_unofficial" | "suno_instrumental" | "suno_add_vocals";
  status: "pending" | "processing" | "completed" | "failed" | "insufficient_credits" | "insufficient_plan";
  createdAt: string;
  errorMessage?: string;
  errorCode?: string;

  input: {
    title?: string;
    lyrics?: string;
    prompt?: string;
    instrumental?: boolean;
    sourceAudioId?: string;
    vocalStyle?: string;
    style?: string;
    negativeTags?: string;
    styleWeight?: number;
    weirdnessConstraint?: number;
    audioWeight?: number;
    coverId?: string;
    trimStart?: number;
    trimEnd?: number;
  };

  output?: {
    audioId: string;           // Storage 路径
    coverId?: string;
    coverWidth?: number;
    coverHeight?: number;
    durationMs: number;
    title: string;
    lyrics: string;
    hasVocals: boolean;
    hasInstrumental: boolean;
    syncedLyrics?: Array<{ text: string; start: number; end: number }>;
  };
}

agent_message/
├── {userId}/{threadId}/
│   ├── music_{audioId}.mp3
│   └── mc_{coverId}.jpg
└── feed/{userId}/
    ├── music_{audioId}.mp3   # Feed 副本
    └── mc_{coverId}.jpg

trackMediaUsage({
  userId, threadId, taskId, toolName,
  provider,                 // suno_unofficial / suno_instrumental / suno_add_vocals
  model,                    // 模型字符串
  durationMs,               // 处理耗时
  outputDurationMs,         // 音频时长（ms）
});