Documentation Index
Fetch the complete documentation index at: https://tech.illasoft.com/llms.txt
Use this file to discover all available pages before exploring further.
Audio 模块是 Kira 的音乐生成和播放工作区，支持歌曲生成（generateMusic）、器乐生成（generateInstrumental）和添加人声（addVocals），与图片和视频编辑器共享同一个 Generator 页面。
组件层次
核心组件
AudioPlayerCard
主音频播放器，位于 Generator 和 Rewind 页面。
components/feature/common/generator/audio-player-card.tsx
| 功能 | 说明 |
|---|
| Howler.js 播放器 | HTML5 音频播放 |
| CD 动画 | 播放时旋转 CD 封面 |
| 同步歌词 | 支持逐字高亮和自动滚动 |
| 进度条 | 拖拽定位，时间显示 |
| 播放控制 | 播放/暂停、循环、歌词切换 |
布局规格
| 参数 | 桌面端 | 移动端 |
|---|
| 卡片宽度 | 424px | 自适应 |
| 卡片高度 | 500px | 自适应 |
| 封面尺寸 | 320×320px | 280×280px |
同步歌词系统
支持逐字级别的歌词同步高亮：
- SyncedWord 数据结构包含
text、start、end 时间戳
- 段落/行分组，支持 CJK（中日韩）智能空格检测
- 实时高亮当前词，fill 动画效果
- 自动滚动到当前行
- 无同步数据时降级为纯文本歌词
CanvasAudioPlayer
Canvas 集成播放器，嵌入聊天画布中。
components/feature/common/generator/canvas-audio-player.tsx
- 布局：桌面端安全宽度的 60%，移动端全宽减边距
- 状态占位卡片：pending/processing 旋转渐变边框、failed 红色边框
OrbitingBorderBeam 动画用于 processing 状态
MusicGenerationCard
聊天消息中的音乐生成状态卡片。
components/feature/common/chat/message/assistant/music-generation-card.tsx
| 状态 | 展示 |
|---|
| pending / processing | 旋转渐变边框 + loading 动画 |
| completed | 音频就绪 |
| failed | 错误信息 + 重试按钮 |
| insufficient_credits / plan | 升级/充值引导 |
components/feature/common/generator/media-selector.tsx
- 合并图片、视频和音频，按
createdAt 排序
- 音频缩略图显示封面 + 音符图标（无封面时显示默认图标）
- 处理中的音频显示
OrbitingBorderBeam 动画（青色）
- 类型特定的状态指示器
工具栏
PC 端
| 工具栏 | 位置 | 包含 |
|---|
PCAudioToolBar | 右侧边栏 | MusicGenerate, InstrumentalGenerate, AddVocals |
PCTopToolBar | 顶部居中 | NewThread, Upload, AudioExport, Backward, Forward, Delete |
移动端
| 工具栏 | 位置 | 包含 |
|---|
MobileAudioToolBar | 底部 | AI 标签页: MusicGenerate, InstrumentalGenerate, AddVocals；Basic 标签页: AudioExport, Backward, Forward, Delete |
移动端音频工具栏使用 AI/Basic 标签页切换，与图片和视频工具栏保持一致的交互模式。
工具按钮
| 工具 | 组件 | EditMode | 条件 |
|---|
| 歌曲生成 | music-generate.tsx | generateMusic | 有 Credits |
| 器乐生成 | instrumental-generate.tsx | generateInstrumental | 有 Credits |
| 添加人声 | add-vocals.tsx | addVocals | 音频已完成 + hasVocals === false |
| 音频修剪 | trim-audio.tsx | trimAudio | 音频已完成（0 credits） |
| 音频导出 | audio-export.tsx | — | 音频已完成 |
Selector 组件
MusicSelector
歌曲生成配置面板。
| 配置项 | 说明 |
|---|
| 歌曲标题 | 可选，AI 可自动生成 |
| 歌词 | 文本输入，支持结构标签 |
| 音乐提示词 | 风格/情绪描述 |
| 封面图片 | 可选上传，使用 ImageUploaderProvider |
::::poisson-function function=generateMusic title="..." lyrics="..." prompt="..." coverImageId="..."
::::
InstrumentalSelector
器乐生成配置面板。
| 配置项 | 说明 |
|---|
| 曲目标题 | 可选 |
| 器乐提示词 | 风格描述（必填） |
| 封面图片 | 可选上传 |
AudioTrimSelector
音频修剪配置面板（新增）。纯前端 timeline UI 选 start/end 区间，后端 ffmpeg 剪切，0 credits。
文件：components/feature/common/generator/audio-trim-selector.tsx
AddVocalsSelector
人声添加配置面板。
| 配置项 | 说明 |
|---|
| 人声风格 | 风格标签（必填） |
| 人声提示词 | 人声描述（必填） |
| 排除标签 | 可选 |
| 高级设置 | Style Weight / Weirdness / Audio Weight 滑块 (0-100) |
音频生成流程
进入音乐生成模式
用户点击 MusicGenerate / InstrumentalGenerate / AddVocals 按钮 → editMode 设为对应模式
配置参数
Selector 面板展开，用户设置歌词、提示词、封面等参数
发送请求
确认后通过 function-call 格式发送到 AI Agent
实时状态更新
WebSocket 推送音频状态变更，UI 实时更新
播放音频
生成完成后 AudioPlayerCard 自动加载播放
实时通知
通过 Centrifugo WebSocket 接收音频状态更新：
hooks/useMusicNotificationHandler.ts
| 消息类型 | 处理 |
|---|
audio_status | 统一通知类型，根据 audio.status 字段更新 versions 缓存、当前选中音频、消息列表 |
更新目标
- Versions 缓存 — TanStack Query 数据中的音频列表
- 当前选中音频 — Zustand store 中的
currentSelectAudio
- Messages 缓存 — 聊天消息列表中的音乐生成卡片
- TempMessages 缓存 — 临时消息中的音乐生成卡片
状态管理
// store/poisson.ts
interface PoissonState {
currentSelectAudio?: Audio; // 当前选中的音频
currentSelectMediaType: "image" | "video" | "audio"; // 当前媒体类型
editMode: EditMode; // 包含音乐相关模式
}
| 方法 | 说明 |
|---|
setCurrentSelectAudio(threadId, audio) | 设置当前选中音频 |
getCurrentSelectAudio(threadId) | 获取当前选中音频 |
setEditMode(threadId, "generateMusic") | 进入歌曲生成模式 |
音频数据模型
// 新的 envelope 结构（input/output 分离），对应 kira-be AudioSchema
interface Audio {
taskId: string;
toolCallId?: string;
toolName?: string;
provider: "suno_unofficial" | "suno_instrumental" | "suno_add_vocals";
status: "pending" | "processing" | "completed" | "failed"
| "insufficient_credits" | "insufficient_plan";
createdAt: string;
errorMessage?: string | null;
errorCode?: string | null;
input: {
title?: string;
lyrics?: string;
prompt?: string;
instrumental?: boolean;
sourceAudioId?: string; // addVocals / trimAudio / initializeWithAudio
vocalStyle?: string; // addVocals
style?: string;
negativeTags?: string;
styleWeight?: number;
weirdnessConstraint?: number;
audioWeight?: number;
coverId?: string;
trimStart?: number;
trimEnd?: number;
};
output?: {
audioId: string;
coverId?: string;
coverWidth?: number;
coverHeight?: number;
durationMs: number;
title: string;
lyrics: string;
hasVocals: boolean;
hasInstrumental: boolean;
syncedLyrics?: Array<{ text: string; start: number; end: number }>;
};
// 后端返回时补签名 URL
url?: string;
coverUrl?: string;
blurhash?: string;
}
Hooks
| Hook | 文件 | 说明 |
|---|
useAudioPlayer | use-audio-player.ts | Howler.js 播放器状态 (play/pause/seek/volume/loop) |
useSubmitMusicTask | useSubmitMusicTask.ts | 重新提交被阻塞的音乐任务 |
useMusicNotificationHandler | useMusicNotificationHandler.ts | WebSocket 音频状态通知处理 |
Feed 音频
音频可以发布到用户 Feed，Feed 详情页复用 Generator 的 AudioPlayerCard：
FeedAudioPlayer (components/feature/common/feed/feed-audio-player.tsx) 把 FeedAudio 转换为 VersionAudio（output.audioId = audio.audioId 等），然后用同一个 AudioPlayerCard 渲染- 卡片尺寸：PC 520×560px，Mobile 420×500px
| 平台 | 组件 | 展示 |
|---|
| PC | PCFeedCard + FeedAudioPlayer | 封面图 + 完整播放器 |
| Mobile | MobileFeedCard + FeedAudioPlayer | 同上，响应式尺寸 |
相关文档
