I added exactly that to a browser audio tool: the mixed-down audio plus a single still picture, written as an .mp4. It is not a video editor, and the picture never changes. Still, producing a file that every player and uploader accepts turned out to be mostly a file-format problem, not an encoding problem. This post is about that part.

What WebCodecs gives you, and what it doesn't

In Chrome, AudioEncoder produces raw AAC packets (1024 samples each) and VideoEncoder produces H.264 frames. Neither writes a file, so the MP4 container is my job: boxes, sample tables, offsets.

The plan:

1. Encode the audio to AAC. (An M4A writer already existed, so this reuses its encoder path.)
2. Draw one picture on an OffscreenCanvas and encode it as H.264.
3. Write an MP4 with two tracks, an audio track and a video track.

Layout: index first, data after, nothing held in memory

I wanted a "fast start" file, with the moov index before the mdat data, so a browser can start playing before the download finishes. But the index depends on sizes of everything that comes after it, and the audio can be long. I don't want to hold an hour of AAC in memory just to write a header.

So the file is assembled as:

ftyp | moov | mdat header | all audio packets | all video samples

The packets are written to the output as they are encoded, and once their sizes are all known, the head (ftyp + moov + the mdat header) is built and put in front. Because the sample table stores each track's data as a single chunk, the whole audio track is one chunk and the whole video track is one chunk. That keeps the index small.

The chicken-and-egg offset

The sample table needs to say where each chunk starts (stco / co64). That offset is the size of ftyp + moov + the mdat header, but moov contains the offsets. Its own size depends on them.

The trick I used is dull and works: build moov twice. The offset boxes have a fixed width, so the size doesn't change between passes.

function assemble(ftyp, dataBytes, build) {
  const header = mdatHeader(dataBytes);
  let moov = build(0);                       // wrong offsets, right size
  moov = build(ftyp.length + moov.length + header.length); // right offsets
  /* concatenate ftyp, moov, header */
}

The one place it could go wrong is the offset box width: past 4 GB, 32-bit stco has to become 64-bit co64, and so does the mdat header (a size field of 1 followed by a 64-bit length). Both are chosen by the data size, which is known before the first pass, so the width is the same in both passes.

Decision: no edit list

AAC encoders emit a few "priming" samples at the start; the decoder is supposed to skip them. For a plain .m4a, I write an edit list (elst) that trims the priming at the start and the padding at the end, so the decoded length is exactly the mix's length.

For the MP4 I left the edit list out. YouTube's recommended upload settings say "No Edit Lists (or the video might not get processed correctly)", and this file is meant for uploads. There is a cost, and it is not hidden:

• The sound plays every decoded sample, priming included. On the encoder I tested, that lead-in was 2,112 samples, about 48 ms at 44.1 kHz. That is the encoder's number, not a universal constant.
• To keep the two tracks the same length, the picture's last frame is shortened so the video ends with the sound.

In a check against the WAV of the same mix, the sound matched after shifting by exactly that lead-in (the comparison came out at about 47 dB). I'm describing what I measured on one setup, not a guarantee for every browser's encoder. And 48 ms is inaudible for a still-picture upload, but it is a real offset, and I'd rather state it than pretend the file is sample-exact.

The video: one frame a second

A picture that never changes doesn't need 30 frames per second. The track is 1280×720, one frame per second, with a keyframe every 10 seconds. Fewer frames means less encoder time and a smaller file. Keyframes still have to exist at regular intervals so players can seek.

The sample table reflects that: stts gives every sample the same duration, stss lists the keyframes, and ctts (composition offsets) is written only if an encoder actually reorders frames. If any offset is negative, the box is written signed.

Codec profiles are a fallback chain, because browsers differ: try H.264 High, then Main, then Baseline, whichever the encoder reports as supported. In Chrome the software encoder I hit only offered Baseline. The export option is offered at all only if the browser has both an AAC encoder and an H.264 encoder; otherwise the control says it isn't available there.

How I checked it

A muxer can produce something that plays in one player and breaks in another, so a single "it plays" proves little. For a 10-minute project in Chrome 156 I checked:

• ffprobe: H.264 High, 1280×720, 1 fps, yuv420p, plus AAC, with equal track lengths;
• the box order (ftyp, moov, mdat) and no edit-list box anywhere;
• a full ffmpeg decode with no errors;
• macOS AVFoundation reading it, and Chrome's <video> element playing it;
• unit tests that parse the boxes back and check offsets, stts, stss, ctts and co64.

That run produced 601 frames and a 13.0 MB file in 18.1 seconds on that machine. It's one data point on one machine, not a benchmark.

Limits

• The picture is static. This is not a way to make a real video.
• No edit list means a small, known lead-in on the sound.
• Both encoders must exist in the browser; some will not offer it.
• The checks above are Chrome plus a handful of players. They are not a claim that every uploader on earth accepts the file.

Takeaways

• WebCodecs gives you encoded chunks; the container is a separate job.
• For a fast-start file that doesn't buffer, write the data first and build the head afterwards, building the index twice to resolve its own offsets.
• Choose stco vs co64 and the mdat header form from the data size before the first pass, so sizes don't shift.
• An edit list is a tradeoff: exact length versus compatibility with what the destination recommends. Write down which one you chose.
• Verify with more than one consumer, and report measurements as measurements.

For sixty days, analytics showed the same pattern four times: someone dropped a lone -wal file. All four were on Windows. Three of them dropped the real project about a minute later. One left.

The sniffing already knew what they had dropped. The message said so: this is the write-ahead log, not the project; drop it together with the project of the same name without -wal. That wording is accurate. It still failed half of them on the first try, and one of them for good. Here is why, and what I changed.

What File Explorer shows by default

Windows File Explorer ships with "Hide extensions for known file types" turned on. For a registered type, Explorer lists the file by its stem. For a type Windows does not know, it shows the whole name.

Audacity projects are often associated with Audacity, so a project named My Song.aup4 can appear in Explorer as just:

My Song

The write-ahead log is not a registered type. It keeps its full name:

My Song.aup4-wal

Put those two side by side and the only entry that visibly contains .aup4 is the log. A careful user looking for "the .aup4 file" will pick the wrong one. That is not a misunderstanding of Audacity. It is a misunderstanding of what the file list is showing.

I did not invent this from a theory. It matches the four drops: every one of them was Windows, and three people corrected themselves once they got a second look at the folder. The wording "the project of the same name without -wal" is true, but on a screen that already hides .aup4, it does not point at anything visible.

The fix is in the sentence, not the detector

The detector was fine. A -wal is recognised by SQLite's WAL header, not by its name, and saying "this is not a project" was already correct. What was missing was a concrete name.

When the dropped file is called My Song.aup4-wal, the companion project is recoverable from that string alone:

function companionProject(
  name: string | undefined,
  suffix: "-wal" | "-shm",
): { file: string; stem: string } | null {
  const match = name
    ? new RegExp(`^(.+)\\.(aup[34])${suffix}$`, "i").exec(name)
    : null;
  return match
    ? { file: `${match[1]}.${match[2]}`, stem: match[1] }
    : null;
}

For My Song.aup4-wal that yields { file: "My Song.aup4", stem: "My Song" }. The error message can then say both forms:

Drop it together with the project My Song.aup4, the file of the same name without -wal (Windows may list it as just "My Song" when "Hide extensions for known file types" is on)…

The same pattern applies to -shm (the WAL index). That file holds no audio at all, and Windows visitors have dropped it alone for the same reason: it is the only name in the folder that still shows an Audacity-looking suffix.

If the dropped name does not match (renamed.bin, song.wav-wal, a bare .aup4-wal), the message falls back to the general wording. Guessing a project name from a rename would be worse than saying nothing specific.

One privacy constraint on the file name

The dropped file's name is useful in the message the user sees. It is not useful in analytics. The name is passed into the message builder and nowhere else — it is never reported as a metric. That keeps the error personal without turning file names into telemetry.

The same care applies to when the hint is shown. The "what you actually dropped" sentence only appears when the file was rejected for what it is (not SQLite, or SQLite but not an Audacity project). A genuine project that fails to open for another reason — corruption, a bad journal, out of memory — must not get a "this is a write-ahead log" speech. That would send the user looking for a companion file that does not exist.

What this is not

This is not a Windows bug report, and it is not a call to force extensions visible. Explorer's default has been this way for a long time, and users are not going to change it for one tool. The tool has to meet them where the file list already is.

It is also not a claim that every lone -wal drop is caused by hidden extensions. Three of four people recovered on their own; one left. Four events in sixty days is a small sample. The change is cheap, tested, and matches a real Windows UI behaviour, so I shipped it. I would not call it proven causation.

Takeaways

• When users repeatedly drop a companion file instead of the main one, look at how the file list renders names, not only at how your format works.
• "Drop the file of the same name without the suffix" is precise and still useless if the suffix was never on screen.
• Derive the missing name from the dropped name when the pattern is unambiguous; fall back when it is not.
• Keep that name in the user-facing sentence. Do not put it in telemetry.
• Show "what you dropped" hints only when the rejection is about identity, not about a later open failure.

The surprising part, for me, was how little code it took. The hard part was noticing that a correct sentence can still point at the wrong icon.

I recently wrote a TNEF reader in TypeScript that runs in the browser. The file format is small, but several details caught me out. Here is what they were and how the parser handles them.

The shape of the file

A TNEF stream starts with a 4-byte signature, 0x223E9F78 (little-endian), followed by a 2-byte key. After that it is a flat run of attributes:

level    (1 byte)   0x01 = message, 0x02 = attachment
id       (4 bytes)
length   (4 bytes)
data     (length bytes)
checksum (2 bytes)

That is 11 bytes of overhead per attribute. Some attributes carry simple things like the subject, sender or dates. Two of them, attMsgProps (0x9003) and attAttachment (0x9005), carry whole MAPI property lists, and most of the useful data lives there: the long attachment names, the compressed RTF body, and the recipients.

There is no nesting for attachments. attAttachRenddata (0x9002) opens a new attachment, and every attachment-level attribute after it (title, data, MAPI props) belongs to that attachment until the next attAttachRenddata. So the parser is a small state machine: "current attachment = the last one opened".

Gotcha 1: match attribute ids on the low word only

The 32-bit attribute id is documented as a type in the high word plus an id in the low word. In practice, writers don't agree on the high word. Matching the full 32-bit value will silently miss attributes from some producers. The fix is to switch on id & 0xFFFF:

const ATT_SUBJECT = 0x8004;
const ATT_ATTACH_DATA = 0x800f;
const ATT_ATTACH_TITLE = 0x8010;
const ATT_ATTACH_RENDDATA = 0x9002;
const ATT_MSG_PROPS = 0x9003;
const ATT_ATTACHMENT = 0x9005;
const ATT_OEM_CODEPAGE = 0x9007;

switch (rawId & 0xffff) { /* ... */ }

Gotcha 2: 8-bit strings have no encoding of their own

TNEF predates universal Unicode. Plain attributes like the subject or the attachment title are bytes in the OEM code page named by attOemCodepage. MAPI PT_STRING8 values are in the message's code page, which can be a different one. If you decode with UTF-8 or Latin-1 while parsing, a Japanese or Cyrillic file name comes out as mojibake, and the damage can't be undone.

So the parser doesn't decode at all. It keeps those strings as raw bytes:

/** An 8-bit string, still in whatever code page its writer used. */
export interface AnsiString {
  ansi: Uint8Array;
}

Only the layer above, which knows which code page applies to which field, turns them into text. PT_UNICODE values are the exception. They are UTF-16LE and can be decoded right away (strip trailing NULs).

Gotcha 3: MAPI property lists are padded, and named properties carry extra baggage

A property list is a count, followed by entries of type (u16), id (u16), an optional name, and the value or values. Two details matter here:

• Padding. Each variable-length value (PT_STRING8, PT_UNICODE, PT_BINARY, PT_OBJECT) is u32 length + bytes, padded to a multiple of 4. Fixed-size values are padded too. Forget this once and every property after it is misaligned.
• Named properties (id >= 0x8000) are followed by a 16-byte property-set GUID, a kind, and then either a 4-byte numeric id or a length-prefixed (and padded) UTF-16 name. Their ids are assigned per store and mean nothing without the name, so I step over them and keep only the standard properties:

if (id >= 0x8000) {
  cursor.skip(16);              // property set GUID
  const kind = cursor.u32();
  if (kind === 0) cursor.skip(4);
  else {
    const n = cursor.u32();
    cursor.skip(n);
    cursor.pad(n);
  }
}

Multi-valued types (flag 0x1000) and all variable-length types start with a value count. A corrupt file can claim four billion values, so the parser checks that count against what could physically fit in the remaining bytes before looping, since each value takes at least four:

if (n > (cursor.bytes.length - cursor.pos) / 4)
  throw new RangeError("MAPI value count past the end");

Gotcha 4: bounds-check every read, but keep what you already have

Every read goes through a tiny Cursor whose need(n) throws when a value would run past the end. That alone stops out-of-bounds reads. What to do with the error is the more interesting decision.

A winmail.dat that was cut short (a failed download, a mail gateway that truncated it) usually still holds complete attachments before the cut. Those attachments are exactly why the person opened the file. So the parser doesn't throw the whole message away. It records truncated: true and returns what it parsed. Property lists write each property into the map as soon as it's read, so a list that fails halfway still hands its first half to the caller. Only two cases are hard failures: a bad signature, or a file with nothing usable in it.

Gotcha 5: which name is the real file name?

An attachment can carry up to three names:

1. attAttachTitle, often an 8.3 short name like QUARTE~1.PDF, in the OEM code page.
2. attAttachTransportFilename.
3. PR_ATTACH_LONG_FILENAME (0x3707) in the attachment's MAPI properties, which is the name the sender actually saw.

Prefer the long MAPI name and fall back to the title. Otherwise users get 8.3 names back and assume the file is broken.

The body: compressed RTF, and sometimes HTML in disguise

The message body is usually PR_RTF_COMPRESSED (0x1009): RTF compressed with Microsoft's LZFu scheme, or stored uncompressed in the "MELA" form. I didn't write my own decompressor. @kenjiuno/decompressrtf handles both, and it was already in the dependency tree through an MSG reader.

What comes out of decompression has one of two shapes:

• Encapsulated HTML ([MS-OXRTFEX]). If the RTF contains \fromhtml1, the original message was HTML. The tags sit in {\*\htmltag …} groups, and RTF-only filler sits between \htmlrtf and \htmlrtf0. Walking the groups and keeping only the HTML parts gives you the original HTML back character for character, so there's no need to render RTF at all.
• Native Rich Text. For a reading pane you only need the text: characters, paragraph breaks and tabs. You skip destinations that are never body text (fonttbl, colortbl, stylesheet, pict, header/footer and so on), honour \ucN for Unicode escapes, and map a handful of symbol words (\emdash, \ldblquote …). The detail that matters is that \'xx hex escapes are bytes in the current font's charset, so you have to parse the font table and map \fcharsetN to a code page (128 → 932, 134 → 936, 204 → 1251, …). Without that, CJK Rich Text turns into garbage.

Routing: trust bytes over names

People rename things. A TNEF stream can arrive as winmail.dat, ATT00001.dat, or with no extension at all, and a .dat file isn't always TNEF. My routing works like this:

• a .dat name goes to the TNEF reader by default;
• TNEF content under any other name is recognised by its first four bytes;
• a .dat whose bytes are actually PST, EML, MBOX or an OLE compound file goes to that reader.

When the signature check fails, the error includes what the first bytes do look like, so the message can say "this is actually a ZIP" instead of a generic "invalid file".

Testing against real files

Hand-made fixtures only prove that you agree with yourself. The tests run on Apache POI's HMEF sample files (Apache-2.0). The extracted attachments must be byte-identical to POI's originals, and the decompressed RTF identical to POI's message.rtf. Two Exchange Online samples check sender, recipient, HTML body and binary attachments. For the cases no public sample covers (embedded messages, CJK Rich Text, named properties, files cut at every offset), I wrote a tiny TNEF writer in the test suite and round-trip through it.

Takeaways

• Match TNEF attribute ids on the low 16 bits.
• Keep 8-bit strings as bytes until you know their code page.
• Respect 4-byte padding in MAPI property lists and skip named properties' GUID and name.
• Sanity-check counts against remaining bytes before looping.
• On truncation, return what you parsed. The attachments are the point.
• Prefer PR_ATTACH_LONG_FILENAME over the 8.3 title.
• For the body, extract encapsulated HTML when it's there, and use per-font code pages for Rich Text.