Manipulating WAV Extra Fields in FFmpeg

This article explains how to manipulate the extra header fields and custom metadata chunks of a WAV (RIFF) file using FFmpeg. Because FFmpeg filters operate on decoded audio frames rather than container structures, modifying container-level "extra fields"—such as the Broadcast Wave Format (bext) chunk, WAVEFORMATEXTENSIBLE headers, or custom RIFF metadata—is accomplished using muxer options and metadata flags rather than an audio filter graph.

Understanding Extra Fields in WAV Files

In the RIFF WAV specification, "extra fields" typically refer to extra header bytes appended to the fmt chunk (common in WAVEFORMATEX or WAVEFORMATEXTENSIBLE structures), custom metadata sub-chunks (such as bext or INFO), or embedded marker data.

FFmpeg's filter engine (-af) is designed for modifying audio samples (e.g., volume, equalization, channel mixing). To inject, modify, or strip extended container fields, FFmpeg relies on its WAV muxer options, codec parameters, and metadata switches.

Writing Broadcast Wave Format (BEXT) Fields

The most common requirement for extra fields in professional audio is the Broadcast Wave Format (bext) chunk, which contains metadata like originator, time reference, and coding history.

To enable and populate the bext extra chunk, use the -write_bext 1 muxer option in combination with the -metadata option:

ffmpeg -i input.wav -c copy -write_bext 1 \
  -metadata description="Final Master Mix" \
  -metadata originator="SoundEngineer" \
  -metadata originator_reference="PROJ-2024-001" \
  -metadata origination_date="2024-01-15" \
  -metadata origination_time="14:30:00" \
  -metadata time_reference="0" \
  output.wav

Supported BEXT Metadata Keys

  • description: ASCII description of the audio sequence.
  • originator: Name of the creator or workstation.
  • originator_reference: Unique reference code.
  • origination_date: Format YYYY-MM-DD.
  • origination_time: Format HH:MM:SS.
  • time_reference: Sample count since midnight (timecode reference).
  • coding_history: Technical history of coding processes.

Modifying Standard RIFF INFO Extra Chunks

If your target application requires arbitrary or standard metadata tags stored within the RIFF INFO list chunk, assign them using standard key-value pairs:

ffmpeg -i input.wav -c copy \
  -metadata title="Track Title" \
  -metadata artist="Artist Name" \
  -metadata comment="Custom Extra Field Data" \
  output.wav

To strip existing extra metadata fields completely to create a minimal, pristine WAV file, use the -map_metadata -1 parameter:

ffmpeg -i input.wav -c copy -map_metadata -1 output_stripped.wav

Handling WAVEFORMATEXTENSIBLE Headers

When dealing with audio with more than two channels or non-standard bit depths, WAV files use an extended format chunk containing a cbSize extra field and a channel mask.

You can force or suppress this extended header structure using the -waveformat_extensible muxer option:

Force Extended Header Structure

ffmpeg -i input.wav -c:a pcm_s24le -waveformat_extensible 1 output_extensible.wav

Force Standard Format Header (Disabling Extensible Chunk)

For compatibility with legacy hardware that cannot parse the WAVEFORMATEXTENSIBLE extra fields:

ffmpeg -i input.wav -c:a pcm_s16le -waveformat_extensible 0 output_legacy.wav

Verifying Extra Fields

To inspect the extra chunks and metadata written to your output WAV file, query the container using ffprobe:

ffprobe -v quiet -show_entries format_tags -of default=noprint_wrappers=1 output.wav