{"record":{"id":"a1b6125b1e4d203f","repo":"remotion-dev/remotion","slug":"unknown-sample-format-boxformat","errorCode":null,"errorMessage":"Unknown sample format ${boxFormat}","messagePattern":"Unknown sample format (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"packages/media-parser/src/containers/iso-base-media/stsd/samples.ts","lineNumber":366,"sourceCode":"\t\t\t\tsize: boxSize,\n\t\t\t\ttype: 'video',\n\t\t\t\twidth,\n\t\t\t\theight,\n\t\t\t\thorizontalResolutionPpi: horizontalResolution,\n\t\t\t\tverticalResolutionPpi: verticalResolution,\n\t\t\t\tspacialQuality,\n\t\t\t\ttemporalQuality,\n\t\t\t\tdataSize,\n\t\t\t\tframeCountPerSample,\n\t\t\t\tcompressorName,\n\t\t\t\tdepth,\n\t\t\t\tcolorTableId,\n\t\t\t\tdescriptors: children,\n\t\t\t},\n\t\t};\n\t}\n\n\tthrow new Error(`Unknown sample format ${boxFormat}`);\n};\n\nexport const parseIsoFormatBoxes = async ({\n\tmaxBytes,\n\tlogLevel,\n\titerator,\n\tcontentLength,\n}: {\n\tmaxBytes: number;\n\tlogLevel: MediaParserLogLevel;\n\titerator: BufferIterator;\n\tcontentLength: number;\n}): Promise<Sample[]> => {\n\tconst samples: Sample[] = [];\n\tconst initialOffset = iterator.counter.getOffset();\n\n\twhile (\n\t\titerator.bytesRemaining() > 0 &&","sourceCodeStart":348,"sourceCodeEnd":384,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/containers/iso-base-media/stsd/samples.ts#L348-L384","documentation":"After the video and audio sample-entry branches, the parser throws if the box format (FourCC) was neither recognized as a known video nor audio tag. This is a coverage gap: the file contains a sample entry for a codec the parser does not know about (e.g. a subtitle, hint, or metadata track, or an exotic codec).","triggerScenarios":"parseIsoFormatBox reaches the end with a boxFormat not present in videoTags or audioTags — e.g. 'text', 'tx3g', 'sbtl', 'wma ', or a proprietary codec FourCC.","commonSituations":"MP4 files containing subtitle tracks (tx3g), timed metadata, hint tracks for streaming, or files authored by tools that emit non-standard FourCCs. Also common with screen recordings that embed system audio as an unusual codec.","solutions":["Identify the unknown track: `ffprobe -show_streams input.mp4` and look for non-video/non-audio stream types.","Strip the unrecognized track: `ffmpeg -i input.mp4 -map 0:v -map 0:a cleaned.mp4` to keep only video and audio.","If the file is valid and you need that codec, request upstream support for that FourCC.","Verify you are passing the correct parser entry point; a non-ISOBMFF file fed to this parser would produce unknown box formats."],"exampleFix":"// before: file with subtitle/hint track throws 'Unknown sample format tx3g'\nffmpeg -i input.mp4 -map 0:v:0 -map 0:a:0 -c copy video_audio_only.mp4\n// after: only video+audio tracks remain, parser succeeds","handlingStrategy":"validation","validationCode":"// List sample-entry FourCCs with ffprobe and filter out unsupported tracks\n// ffprobe -show_entries stream=codec_name,codec_tag_string -of json input.mp4\n// Then strip non-video/non-audio tracks:\n// ffmpeg -i input.mp4 -map 0:v -map 0:a -c copy cleaned.mp4","typeGuard":"const SUPPORTED_FOURCC = new Set(['avc1','avc3','hev1','hvc1','mp4a','ac-3','ec-3','opus','Opus','vp09','av01']);\nfunction isSupportedSampleFormat(fourcc: string): boolean {\n  return SUPPORTED_FOURCC.has(fourcc);\n}","tryCatchPattern":"try {\n  await parseMedia({src, fields: {dimensions: true}});\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unknown sample format')) {\n    // strip unsupported tracks with ffmpeg and retry\n  } else throw err;\n}","preventionTips":["Strip subtitle/hint/metadata tracks with ffmpeg -map before parsing.","Maintain a whitelist of supported codec FourCCs for your input pipeline.","Validate uploads with ffprobe and reject or normalize files with unknown codecs."],"tags":["media-parser","isobmff","stsd","parser-coverage","fourcc","mp4"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}