feat: add Volcengine file transcription support

- Create volcFileApi.ts with flash (sync) recognize API using base64 upload
- Add executeVolc function in useFileTranscription hook
- Update VolcProvider to mark fileTranscription as compatible
- All providers now support file transcription

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: XimilalaXiang

frontend/src/hooks/useFileTranscription.ts

@@ -52,6 +52,11 @@ import {
   type AssemblyAIWord,
   type AssemblyAIUtterance,
 } from '../utils/assemblyaiFileApi'
+import {
+  transcribeFile as volcTranscribeFile,
+  type VolcWord,
+  type VolcUtterance,
+} from '../utils/volcFileApi'
 
 /* ─── Soniox result conversion ──────────────────────────────── */
 
@@ -802,6 +807,91 @@ async function executeAssemblyAI(
   return { transcript, tokens, segments, speakers, durationMs }
 }
 
+/* ─── Volcengine result conversion ──────────────────────────── */
+
+function volcWordsToTokens(words: VolcWord[]): TranscriptTokenData[] {
+  return words.map((w) => ({
+    text: w.text,
+    isFinal: true as const,
+    startMs: w.start_time,
+    endMs: w.end_time,
+    confidence: w.confidence,
+  }))
+}
+
+function volcUtterancesToSegments(utterances: VolcUtterance[]): TranscriptSegment[] {
+  return utterances.map((u) => ({
+    text: u.text,
+    startMs: u.start_time,
+    endMs: u.end_time,
+    isFinal: true as const,
+    speakerId: u.speaker,
+  }))
+}
+
+function volcExtractSpeakers(utterances: VolcUtterance[]): TranscriptSpeaker[] {
+  const speakerSet = new Set<string>()
+  for (const u of utterances) {
+    if (u.speaker) speakerSet.add(u.speaker)
+  }
+  return Array.from(speakerSet)
+    .sort()
+    .map((id) => ({ id, label: `Speaker ${id}` }))
+}
+
+async function executeVolc(
+  file: File,
+  config: FileTranscriptionConfig,
+  appKey: string,
+  accessKey: string,
+  jobId: string,
+  updateJob: (id: string, u: Record<string, unknown>) => void,
+  signal: AbortSignal,
+): Promise<TranscriptionResult> {
+  updateJob(jobId, { status: 'uploading', progress: 20 })
+
+  updateJob(jobId, { status: 'transcribing', progress: 40 })
+
+  const response = await volcTranscribeFile(
+    appKey,
+    accessKey,
+    file,
+    {
+      enableSpeakerInfo: config.enableSpeakerDiarization,
+      enableItn: true,
+      enablePunc: true,
+      enableDdc: true,
+    },
+    signal,
+  )
+
+  updateJob(jobId, { progress: 90 })
+
+  const transcript = response.result.text ?? ''
+  const utterances = response.result.utterances ?? []
+  const durationMs = response.audio_info.duration ?? 0
+
+  console.debug('[Volcengine] Transcript length:', transcript.length, 'Utterances:', utterances.length, 'Duration:', durationMs)
+
+  if (!transcript && utterances.length === 0) {
+    console.warn('[Volcengine] Empty transcription result. Full response:', JSON.stringify(response))
+    throw new Error('火山引擎返回了空的转录结果，请检查音频文件或尝试其他提供商。')
+  }
+
+  const allWords = utterances.flatMap((u) => u.words ?? [])
+  const tokens: TranscriptTokenData[] = allWords.length > 0
+    ? volcWordsToTokens(allWords)
+    : [{ text: transcript, isFinal: true as const, startMs: 0, endMs: durationMs }]
+
+  const segments: TranscriptSegment[] = utterances.length > 0
+    ? volcUtterancesToSegments(utterances)
+    : [{ text: transcript.trim(), startMs: 0, endMs: durationMs, isFinal: true as const }]
+
+  const speakers = volcExtractSpeakers(utterances)
+
+  return { transcript, tokens, segments, speakers, durationMs }
+}
+
 /* ─── Deepgram helpers ─────────────────────────────────────── */
 
 function parseDeepgramResponse(response: import('../utils/deepgramFileApi').DeepgramFileTranscriptionResponse) {
@@ -915,6 +1005,12 @@ export function useFileTranscription() {
       if (!apiToken || !accountId) {
         throw new Error('Cloudflare API Token 或 Account ID 未配置')
       }
+    } else if (providerId === 'volc') {
+      const appKey = providerConfig?.appKey as string | undefined
+      const accessKey = providerConfig?.accessKey as string | undefined
+      if (!appKey || !accessKey) {
+        throw new Error('火山引擎 APP ID 或 Access Token 未配置')
+      }
     } else if (!apiKey) {
       throw new Error(`${providerId} API Key not configured`)
     }
@@ -951,6 +1047,10 @@ export function useFileTranscription() {
           result = await executeDeepgram(file, config, apiKey!, jobId, updateJob, controller.signal)
         } else if (providerId === 'assemblyai') {
           result = await executeAssemblyAI(file, config, apiKey!, jobId, updateJob, controller.signal)
+        } else if (providerId === 'volc') {
+          const volcAppKey = providerConfig?.appKey as string
+          const volcAccessKey = providerConfig?.accessKey as string
+          result = await executeVolc(file, config, volcAppKey, volcAccessKey, jobId, updateJob, controller.signal)
         } else {
           result = await executeSoniox(file, config, apiKey!, jobId, updateJob, controller.signal)
         }

frontend/src/providers/implementations/VolcProvider.ts

@@ -22,7 +22,7 @@ export class VolcProvider extends BaseASRProvider {
   readonly info: ASRProviderInfo = {
     id: 'volc' as ASRVendor,
     name: '火山引擎',
-    description: '字节跳动旗下语音识别服务，支持中文优化',
+    description: '字节跳动旗下语音识别服务，支持中文优化，实时 + 文件转录',
     type: 'cloud',
     supportsStreaming: true,
     capabilities: {
@@ -48,7 +48,10 @@ export class VolcProvider extends BaseASRProvider {
           acceptedFileKinds: ['audio'],
         },
         fileTranscription: {
-          availability: 'unsupported',
+          availability: 'compatible',
+          executionMode: 'single-request',
+          inputSources: ['file'],
+          acceptedFileKinds: ['audio'],
         },
       },
       supportsConfigTest: true,

frontend/src/utils/volcFileApi.ts

@@ -0,0 +1,110 @@
+/**
+ * 火山引擎 豆包语音 — 大模型录音文件极速版识别 API
+ *
+ * 同步模式：一次请求即返回识别结果
+ * 音频限制：≤ 2h / ≤ 100MB，支持 WAV/MP3/OGG
+ * 认证方式：Header 传 AppKey + AccessKey（旧版控制台）
+ */
+
+const VOLC_RECOGNIZE_URL = 'https://openspeech.bytedance.com/api/v3/auc/bigmodel/recognize/flash'
+
+/* ─── Response types ──────────────────────────────────────── */
+
+export interface VolcWord {
+  text: string
+  start_time: number
+  end_time: number
+  confidence: number
+}
+
+export interface VolcUtterance {
+  text: string
+  start_time: number
+  end_time: number
+  words?: VolcWord[]
+  speaker?: string
+}
+
+export interface VolcRecognizeResponse {
+  audio_info: {
+    duration: number
+  }
+  result: {
+    text: string
+    utterances?: VolcUtterance[]
+    additions?: {
+      duration?: string
+    }
+  }
+}
+
+export interface VolcTranscribeParams {
+  enableSpeakerInfo?: boolean
+  enableItn?: boolean
+  enablePunc?: boolean
+  enableDdc?: boolean
+}
+
+/* ─── Helpers ─────────────────────────────────────────────── */
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer)
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i])
+  }
+  return btoa(binary)
+}
+
+/* ─── Transcribe file (flash / sync) ──────────────────────── */
+
+export async function transcribeFile(
+  appKey: string,
+  accessKey: string,
+  file: File,
+  params: VolcTranscribeParams = {},
+  signal?: AbortSignal,
+): Promise<VolcRecognizeResponse> {
+  const buffer = await file.arrayBuffer()
+  const base64Data = arrayBufferToBase64(buffer)
+
+  const requestId = crypto.randomUUID()
+
+  const headers: Record<string, string> = {
+    'X-Api-App-Key': appKey,
+    'X-Api-Access-Key': accessKey,
+    'X-Api-Resource-Id': 'volc.bigasr.auc_turbo',
+    'X-Api-Request-Id': requestId,
+    'X-Api-Sequence': '-1',
+    'Content-Type': 'application/json',
+  }
+
+  const body = {
+    user: { uid: appKey },
+    audio: { data: base64Data },
+    request: {
+      model_name: 'bigmodel',
+      enable_itn: params.enableItn ?? true,
+      enable_punc: params.enablePunc ?? true,
+      enable_ddc: params.enableDdc ?? true,
+      enable_speaker_info: params.enableSpeakerInfo ?? false,
+    },
+  }
+
+  const res = await fetch(VOLC_RECOGNIZE_URL, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal,
+  })
+
+  const statusCode = res.headers.get('X-Api-Status-Code')
+  const statusMessage = res.headers.get('X-Api-Message')
+
+  if (!res.ok || (statusCode && statusCode !== '20000000')) {
+    const errMsg = statusMessage || `Volcengine API error (${statusCode || res.status})`
+    throw new Error(errMsg)
+  }
+
+  return res.json()
+}