오디오 분리
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
현재 SoT. Media L2 디먹스(
sume/audio-detach-1.0, #5953). dest와 prod. 클립 검사가 아닙니다 — 검사는 비디오 검사입니다. 여러 구간이 필요하면 한 번 분리한 뒤 타임라인 오디오로 쪼개세요.
Audio detach 1.0은 워크스페이스의 하나의 media.sume.com 비디오를
받아 새 오디오 아티팩트를 반환합니다. 기본은 샘플 정확 wav
(pcm_s16le)입니다 — timeline_create audio.url,
POST /v1/timeline-1.0/audio, STT가 원하는 형태입니다. 비디오는
건드리지 않습니다. 서버가 워커 미디어 런타임에서 ffmpeg를
컴파일합니다(apps/api/src/routes.ts createAudioDetachV1 /
submitSumeAudioDetachJob).
GET /v1/audio-detach/:id는 없습니다. Job 봉투로 폴링하세요:
호스티드 MCP: audio_detach(packages/mcp-server/src/mcp.ts). 쓰기는
idempotency_key가 필요합니다(OAuth에서는 mcp:write). 흐름:
audio_detach → jobs_wait → jobs_result.
분리 만들기
필수: video_url(이 워크스페이스의 media.sume.com 아티팩트 또는
에셋). 공개 인터넷 fetch는 없습니다. 먼저 가져오세요
(POST /v1/media-imports). Idempotency-Key는 필수입니다.
선택: format, range, channels, sample_rate, 평소의 mode /
webhook_url / wait_timeout_seconds 통신 필드입니다.
기본 mode는 **async**입니다. mode: "sync"를 주면 최대 30초
기다리고 끝난 Job을 200으로 주거나, 202로 폴링합니다.
성공한 submit은 Job을 반환합니다(request_id가 Job id). result_ready이면
GET /v1/jobs/:id/result는 kind: audio_detach이고 audio_url(새
artf_), duration_seconds, format, channels, sample_rate(생략 시
null — 소스에서 상속), source_duration_seconds, 선택적 range /
warnings[]를 담습니다.
공개 요금: Job당 $0.01(AUDIO_DETACH_PUBLIC_PRICING; 라이브는
GET /v1/catalog). 프로바이더 추론 없음 — 워커 ffmpeg만.
프로그램
| 필드 | 효과 |
|---|---|
format | wav(기본, pcm_s16le 샘플 정확) 또는 mp3(128 kbps). |
range | 선택 { start, end? } 초. 생략하면 트랙 전체. end를 생략하면 열린 구간. |
channels | source(기본) 또는 mono. |
sample_rate | 16000 | 44100 | 48000. 생략하면 소스를 상속. 16000 + channels: "mono"가 STT 형태. |
상한(packages/api-contract/src/index.ts): 소스 ≤ 1800초; 출력 ≤
900초. 트랙 전체가 900초를 넘으면 range가 필요합니다.
오디오 트랙이 없는 소스는 detach_source_has_no_audio로 실패합니다.
먼저 비디오 검사로 probe.has_audio를
확인하세요(frames: false면 충분).
거절(안정 코드)
| 코드 | 언제 |
|---|---|
audio_detach_range_empty | range.end ≤ range.start, 또는 구간이 900초보다 김. |
detach_source_has_no_audio | 소스에 오디오 트랙이 없음(워커). |
detach_start_past_source | range.start가 프로브된 길이보다 뒤(워커). |
ffmpeg_fields_rejected | 클라이언트가 af / filter / ffmpeg / cmd / codec 등을 보냄. 서버가 ffmpeg를 컴파일합니다. |
unsupported_media_source | video_url이 Sume 미디어 호스트가 아님. |
source_not_found | 죽은 또는 다른 워크스페이스 media.sume.com URL. |
unsupported_media_type | HEAD가 비디오가 아님. |
source_duration_exceeded | 소스가 1800초보다 김(워커). |
호스트 밖 URL(https://example.com/…)은 접수에서 거절됩니다. 먼저
가져오세요.
이 표면이 아닌 것
| 필요한 일 | 쓸 것 |
|---|---|
| 프로브 / 스틸 / 선택적 STT | 비디오 검사 |
t의 소스 크기 프레임 | 비디오 프레임 |
| 새 MP4 컷 | 비디오 트림 |
| 픽셀 패스(dim / crop) | 비디오 필터 |
| 한 트랙에서 여러 오디오 구간 | 한 번 분리한 뒤 타임라인 오디오 operation: "split" |
| 여러 클립 시퀀스 | Timeline 1.0 |