Audio detach
Current SoT. Media L2 demux (
sume/audio-detach-1.0, #5953). Dest and prod. This is not clip inspection. For clip inspection, use video inspect. For many ranges, detach once. Then split with timeline audio.
Audio detach 1.0 takes one workspace media.sume.com video and
returns a new audio artifact. The default is sample-exact wav
(pcm_s16le). timeline_create audio.url,
POST /v1/timeline-1.0/audio, and speech-to-text use this format. The video
does not change. The server compiles ffmpeg on the worker media runtime
(apps/api/src/routes.ts createAudioDetachV1 /
submitSumeAudioDetachJob).
There is no GET /v1/audio-detach/:id. Poll the job envelope:
Hosted MCP: audio_detach (packages/mcp-server/src/mcp.ts). Writes
need idempotency_key (and mcp:write under OAuth). Flow:
audio_detach → jobs_wait → jobs_result.
Create a detach
Required: video_url (this workspace’s media.sume.com artifact or
asset). The server does not fetch from the open internet. Import the file first
(POST /v1/media-imports). Idempotency-Key is required.
Optional: format, range, channels, sample_rate, and the usual
mode / webhook_url / wait_timeout_seconds communication fields.
The default mode is async. To wait for a maximum of 30
seconds for a 200 completed job, pass mode: "sync". Otherwise, you get
202 and must poll.
A successful submit returns a job (request_id is the job id). When
result_ready is true, GET /v1/jobs/:id/result is kind: audio_detach and
contains audio_url (new artf_), duration_seconds, format, channels,
sample_rate (null when omitted, because the value comes from the source),
source_duration_seconds, and optional range / warnings[].
Each job uses a flat number of credits. The API rate card lists the current credits. The job uses only worker ffmpeg, with no provider inference.
Program
| Field | Effect |
|---|---|
format | wav (default, pcm_s16le sample-exact) or mp3 (128 kbps). |
range | Optional { start, end? } seconds. Omit it for the whole track. When you omit end, the range is open-ended. |
channels | source (default) or mono. |
sample_rate | 16000 | 44100 | 48000. Omit it to inherit the source. 16000 + channels: "mono" is the STT shape. |
Caps (from packages/api-contract/src/index.ts): source ≤ 1800 s,
output ≤ 900 s. A whole track longer than 900 s needs a range.
A source with no audio track fails with detach_source_has_no_audio. First,
use video inspect to examine probe.has_audio
(frames: false is sufficient).
Refusals (stable codes)
| Code | When |
|---|---|
audio_detach_range_empty | range.end ≤ range.start, or the range is longer than 900 s. |
detach_source_has_no_audio | The source has no audio track (worker). |
detach_start_past_source | range.start is more than the probed duration (worker). |
ffmpeg_fields_rejected | The client sent af / filter / ffmpeg / cmd / codec / similar fields. The server compiles ffmpeg. |
unsupported_media_source | video_url is not on the Sume media host. |
source_not_found | A dead media.sume.com URL, or one from a different workspace. |
unsupported_media_type | HEAD is not a video. |
source_duration_exceeded | The source is longer than 1800 s (worker). |
The server rejects off-host URLs (https://example.com/…) at admit. Import the file first.
Not this surface
| Need | Use |
|---|---|
| Probe / stills / optional STT | Video inspect |
Exact frame at t, source size | Video frames |
| A new MP4 cut | Video trim |
| Pixel pass (dim / crop) | Video filter |
| Many audio ranges from one track | Detach once, then timeline audio operation: "split" |
| Sequence several clips | Timeline 1.0 |