nilaoda/N_m3u8DL-RE · error · Exception

Mp4 box names must be 4 characters long

Error message

Mp4 box names must be 4 characters long

What it means

MP4Parser.TypeFromString converts a 4-character box type name into a packed 32-bit code (each char shifted 8 bits). MP4 box types are defined as exactly four characters, so any other length is rejected with this exception — a programming/API misuse guard.

Solutions

1. Correct the box name passed to .Box()/.FullBox() to exactly 4 ASCII characters (e.g. "moov", "trak", "mdia").
2. If the target is a nested box, chain separate .Box() calls instead of passing a slash-separated name.
3. Check for accidental whitespace or truncated string literals in the parser setup code.

Example fix

// before
parser.Box("moov/trak", MP4Parser.Children);

// after
parser.Box("moov", MP4Parser.Children)
      .Box("trak", MP4Parser.Children);

static void EnsureBoxName(string name)
{
    if (name?.Length != 4 || name.Any(c => c > 127))
        throw new ArgumentException($"MP4 box name must be 4 ASCII chars, got: '{name}'");
}

When it happens

Trigger: Passing a string of length other than 4 to MP4Parser box-builder methods (e.g. .Box("moovv", ...) or .Box("", ...)) — the name flows into TypeFromString via the typeCode helper.

Common situations: Typo in a box name when writing custom parsing code, truncation of a box name variable, or confusing a multi-character path like "moov/trak" with a single box name.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• PSSH version can only be 0 or 1
• MDHD version can only be 0 or 1
• TFDT version can only be 0 or 1
• A TFHD box should have a valid flags value
• Bad vtt!

AI-assisted analysis of nilaoda/N_m3u8DL-RE@e113dee70c (2026-09-13). Data as JSON: /api/errors/6c3d451c5da129d1. Report an issue: GitHub.

Appendix: source

Thrown at src/N_m3u8DL-RE.Parser/Mp4/MP4Parser.cs:213

                + /* additional 64-bit size field */ (box.Has64BitSize ? 8 : 0)
                + /* version and flags for a "full" box */ (box.Flags != 0 ? 4 : 0);
        }

        public static string TypeToString(long type)
        {
            return Encoding.UTF8.GetString(new byte[]
            {
                 (byte)((type >> 24) & 0xff),
                 (byte)((type >> 16) & 0xff),
                 (byte)((type >> 8) & 0xff),
                 (byte)(type & 0xff)
            });
        }

        private static int TypeFromString(string name)
        {
            if (name.Length != 4)
                throw new Exception("Mp4 box names must be 4 characters long");
            var code = 0;
            foreach (var chr in name) {
                code = (code << 8) | chr;
            }
            return code;
        }

        public MP4Parser Box(string type, BoxHandler handler)
        {
            var typeCode = TypeFromString(type);
            this.Headers[typeCode] = (int)BoxType.BASIC_BOX;
            this.BoxDefinitions[typeCode] = handler;
            return this;
        }

        public MP4Parser FullBox(string type, BoxHandler handler)
        {
            var typeCode = TypeFromString(type);

View on GitHub (pinned to e113dee70c)