RFC 9639
Free Lossless Audio Codec (FLAC)
RFC 9639: Free Lossless Audio Codec (FLAC) ๐
Okay bestie, this one is the official spec for FLAC ๐ง, and it was written by M.Q.C. van Beurden and A. Weaver ๐. It's from the IETF (Internet Engineering Task Force) and it's a Standards Track document ๐, which means it's the proper, fully official kind. It was published in December 2024, and its ISSN is 2070-1721. It doesn't obsolete or update any other RFCs, since its header doesn't list any.
Abstract โจ
Okay so this document defines the Free Lossless Audio Codec (FLAC) format and its streamable subset ๐ฆ. FLAC exists to shrink the storage space that digital audio takes up, and it does that losslessly, meaning no information gets lost ๐. It's called "free" because the spec is open and the reference implementation is open source ๐ซถ. Compared to other lossless audio formats, FLAC is low complexity and doesn't need much computing power to encode or decode ๐ . Decoders have been built independently for loads of different platforms, and both encoding and decoding can be done without floating-point arithmetic ๐ฅ.
Status of This Memo
This is an Internet Standards Track document ๐.
This document is a product of the Internet Engineering Task Force (IETF) ๐. It represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication โจ. If you want more info on Internet Standards, check out Section 2 of RFC 7841 ๐ง.
For the current status of this document, any errata, and how to send feedback, head to https://www.rfc-editor.org/info/rfc9639 ๐.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved ๐.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which you can find at https://trustee.ietf.org/license-info as in effect on the date of publication ๐. Please read these carefully, because they spell out your rights and restrictions for this document ๐ซถ. Code Components extracted from this document must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Revised BSD License โ ๏ธ.
Table of Contents ๐ฆ
1. Introduction
2. Notation and Conventions
3. Definitions
4. Conceptual Overview
4.1. Blocking
4.2. Interchannel Decorrelation
4.3. Prediction
4.4. Residual Coding
5. Format Principles
6. Format Layout Overview
7. Streamable Subset
8. File-Level Metadata
8.1. Metadata Block Header
8.2. Streaminfo
8.3. Padding
8.4. Application
8.5. Seek Table
8.5.1. Seek Point
8.6. Vorbis Comment
8.6.1. Standard Field Names
8.6.2. Channel Mask
8.7. Cuesheet
8.7.1. Cuesheet Track
8.8. Picture
9. Frame Structure
9.1. Frame Header
9.1.1. Block Size Bits
9.1.2. Sample Rate Bits
9.1.3. Channels Bits
9.1.4. Bit Depth Bits
9.1.5. Coded Number
9.1.6. Uncommon Block Size
9.1.7. Uncommon Sample Rate
9.1.8. Frame Header CRC
9.2. Subframes
9.2.1. Subframe Header
9.2.2. Wasted Bits per Sample
9.2.3. Constant Subframe
9.2.4. Verbatim Subframe
9.2.5. Fixed Predictor Subframe
9.2.6. Linear Predictor Subframe
9.2.7. Coded Residual
9.3. Frame Footer
10. Container Mappings
10.1. Ogg Mapping
10.2. Matroska Mapping
10.3. ISO Base Media File Format (MP4) Mapping
11. Security Considerations
12. IANA Considerations
12.1. Media Type Registration
12.2. FLAC Application Metadata Block IDs Registry
13. References
13.1. Normative References
13.2. Informative References
Appendix A. Numerical Considerations
A.1. Determining the Necessary Data Type Size
A.2. Stereo Decorrelation
A.3. Prediction
A.4. Residual
A.5. Rice Coding
Appendix B. Past Format Changes
B.1. Addition of Blocking Strategy Bit
B.2. Restriction of Encoded Residual Samples
B.3. Addition of 5-Bit Rice Parameters
B.4. Restriction of LPC Shift to Non-negative Values
Appendix C. Interoperability Considerations
C.1. Features outside of the Streamable Subset
C.2. Variable Block Size
C.3. 5-Bit Rice Parameters
C.4. Rice Escape Code
C.5. Uncommon Block Size
C.6. Uncommon Bit Depth
C.7. Multi-Channel Audio and Uncommon Sample Rates
C.8. Changing Audio Properties Mid-Stream
Appendix D. Examples
D.1. Decoding Example 1
D.1.1. Example File 1 in Hexadecimal Representation
D.1.2. Example File 1 in Binary Representation
D.1.3. Signature and Streaminfo
D.1.4. Audio Frames
D.2. Decoding Example 2
D.2.1. Example File 2 in Hexadecimal Representation
D.2.2. Example File 2 in Binary Representation (Only Audio
Frames)
D.2.3. Streaminfo Metadata Block
D.2.4. Seek Table
D.2.5. Vorbis Comment
D.2.6. Padding
D.2.7. First Audio Frame
D.2.8. Second Audio Frame
D.2.9. MD5 Checksum Verification
D.3. Decoding Example 3
D.3.1. Example File 3 in Hexadecimal Representation
D.3.2. Example File 3 in Binary Representation (Only Audio
Frame)
D.3.3. Streaminfo Metadata Block
D.3.4. Audio Frame
Acknowledgments
Authors' Addresses1. Introduction โจ
Okay so this document is where the FLAC format and its streamable subset get defined ๐ง. FLAC files and streams can hold PCM audio (pulse-code modulated, for the nerds) with anywhere from 1 to 8 channels, sample rates from 1 to 1048575 hertz, and bit depths from 4 to 32 bits ๐ธ. Most FLAC tools were tuned for CD audio, which is PCM with 2 channels, a 44.1 kHz sample rate, and a 16-bit depth ๐ฟ.
FLAC can compress losslessly because audio samples are super correlated with their close neighbors ๐ฆ. General-purpose compressors often lean on dictionaries, run-length coding, or long-term repetition. FLAC is different: it only removes redundancy in the very short term, looking back at 32 samples at most ๐ง. It's giving precision, no cap ๐ .
The coding methods in FLAC work best on PCM audio whose samples are signed and centered around zero โจ. If your audio uses an unsigned representation, it must be transformed to a signed one, the way this document describes, before you can get reasonable compression ๐. FLAC isn't built for audio that isn't PCM ๐.
2. Notation and Conventions ๐ธ
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here ๐.
Values written as u(n) mean an unsigned big-endian integer using n bits ๐. Values written as s(n) mean a signed big-endian integer using n bits, in two's complement ๐ฅ. When n needs to be worked out, it's written as an equation using * (multiplication), / (division), + (addition), or - (subtraction) ๐งฎ. A range of bit counts is written with an ellipsis, like u(m...n) ๐ฆ.
All shifts in this document are arithmetic shifts ๐.
FLAC can store digital audio and other digital signals too, but this document uses audio-specific terminology ๐ง. Generic terms were judged less clear, so if you're using FLAC for non-audio stuff, you're expected to translate the audio terms into generic ones yourself ๐ซถ.
3. Definitions ๐
okay bestie, let's get into the vocab, because you NEED these terms locked in before the rest of the spec makes any sense ๐ โจ
Lossless compression: Shrinking the amount of storage a piece of data takes up without having to delete or irreversibly change any of it along the way. ๐ฆ Decompressing losslessly compressed info gives you back exactly the original data. Iconic. ๐ญ
Lossy compression: Same vibe as lossless, except it's allowed to remove, irreversibly alter, or just approximate some information to save even more space. ๐ซ So when you decompress lossy stuff, you get an approximation of the original. Not the real thing, bestie. ๐
Block: A (short) section of linear PCM audio with one or more channels. ๐ธ
Subblock: All the samples inside a corresponding block for one channel. ๐ง One or more subblocks make up a block, and every subblock in the same block has the same number of samples. Matching energy. ๐ซถ
Frame: A frame header, one or more subframes, and a frame footer. ๐ It encodes the contents of a corresponding block. Main character structure fr fr. ๐
Subframe: An encoded subblock. ๐ฆ All subframes in a frame code for the same number of samples. When interchannel decorrelation is used, a subframe can represent either the (per-sample) average of two subblocks or the (per-sample) difference between two subblocks, instead of a subblock directly. Check Section 4.2 for the deets. ๐
Interchannel samples: A sample count that applies to all channels. ๐ For example, one second of 44.1 kHz audio has 44100 interchannel samples, which means each channel has that many samples. Simple math, slay. ๐งฎโจ
Block size: The number of interchannel samples contained in a block or coded in a frame. ๐
Bit depth or bits per sample: The number of bits used to hold each sample. ๐ฅ This MUST be the same for all subblocks in a block, but MAY be different for different subframes in a frame because of interchannel decorrelation. (See Section 4.2 for the full scoop on interchannel decorrelation.) ๐
Predictor: A model used to predict samples in an audio signal based on past samples. ๐ฎ FLAC uses these predictors to remove redundancy in a signal so it can be compressed. Galaxy brain move. ๐ง ๐
Linear predictor: A predictor that uses linear prediction (see [LinearPrediction]). ๐ธ This is also called linear predictive coding (LPC). โจ Each prediction is a linear combination of past samples, which is where the name comes from. ๐ซถ A linear predictor has a causal discrete-time finite impulse response (see [FIR]). Very technical, very slay. ๐ค
Fixed predictor: A linear predictor whose model parameters are the same across all FLAC files, so they don't need to be stored. ๐ฆ No extra baggage, just vibes. ๐
Predictor order: The number of past samples that a predictor uses. ๐ For example, a 4th order predictor uses the 4 samples directly preceding a certain sample to predict it. ๐ In FLAC, the samples used in a predictor are always consecutive and always the samples directly before the one being predicted. Consistency is everything. ๐
Residual: The audio signal that's left after a predictor has been subtracted from a subblock. ๐ If the predictor did its job and removed redundancy, the remaining samples (the residual samples) will, on average, have a numerical value closer to zero than the original signal. Chef's kiss. ๐จโ๐ณ๐
Rice code: A variable-length code (see [VarLengthCode]). ๐ง It uses a short code for samples close to zero and a progressively longer code for samples further away from zero. ๐ฆ This works because residual samples are often close to zero. Iykyk. ๐
Muxing: Short for multiplexing. ๐ Combining several streams or files into a single stream or file. ๐ธ In the context of this document, muxing specifically means embedding a FLAC stream in a container as described in Section 10. Packaging goals. ๐ฆโจ
4. Conceptual Overview ๐ฆ
okay so, similar to a lot of other audio coders, a FLAC file gets encoded by going through the steps below. ๐ To decode a FLAC file, you run these steps in reverse order, i.e., from bottom to top. ๐
- Blocking (see Section 4.1). ๐ The input is split up into many contiguous blocks. โ๏ธ
- Interchannel Decorrelation (see Section 4.2). ๐ฏโโ๏ธ In the case of stereo streams, the FLAC format lets you transform the left-right signal into a mid-side signal, a left-side signal, or a side-right signal to remove redundancy between channels. ๐ซถ Choosing any of these transformations is done independently for each block. ๐
- Prediction (see Section 4.3). ๐ฎ To remove redundancy in a signal, a predictor is stored for each subblock or for its transformation as formed in the previous step. ๐ง A predictor is a simple mathematical description that can be used, as the name says, to predict a certain sample from the samples that came before it. โจ Since this prediction is rarely exact, the error of the prediction gets passed on to the next stage. ๐ The predictor of each subblock is completely independent from other subblocks. ๐ฆ Because the prediction methods are known to both the encoder and decoder, only the parameters of the predictor need to be included in the compressed stream. ๐ If no usable predictor can be found for a certain subblock, the signal is stored uncompressed, and the next stage is skipped. ๐
- Residual Coding (see Section 4.4). ๐ Since the predictor doesn't describe the signal exactly, the difference between the original signal and the predicted signal (called the error or residual signal) is coded losslessly. ๐ฅ If the predictor is effective, the residual signal will need fewer bits per sample than the original signal. ๐ธ FLAC uses Rice coding, a subset of Golomb coding, with either 4-bit or 5-bit parameters to code the residual signal. ๐ง Very efficient, very iconic. ๐
Also, FLAC specifies a metadata system (see Section 8) that lets arbitrary information about the stream be included at the beginning of the stream. ๐โจ
4.1. Blocking ๐
okay so the block size has a direct effect on the compression ratio. ๐ If the block size is too small, the resulting large number of frames means a disproportionate number of bytes get spent on frame headers. ๐ฉ If the block size is too large, the characteristics of the signal may vary so much that the encoder can't find a good predictor. ๐ To keep encoder/decoder design simple, FLAC imposes a minimum block size of 16 samples, except for the last block, and a maximum block size of 65535 samples. ๐ฆ The last block is allowed to be smaller than 16 samples so it can match the length of the encoded audio without using padding. โจ
The block size doesn't have to be constant in a FLAC file, but it's often difficult to find the optimal arrangement of block sizes for maximum compression. ๐ Because of this, a FLAC stream has explicitly either a constant or variable block size throughout, and it stores a block number instead of a sample number to slightly improve compression when the stream has a constant block size. ๐ซถ Small wins add up, bestie. ๐
4.2. Interchannel Decorrelation ๐ฏโโ๏ธ
okay so channels are correlated in lots of audio files. ๐ซถ The FLAC format can exploit this correlation in stereo files by coding an average of all samples in both subblocks (a mid channel) or the difference between all samples in both subblocks (a side channel), instead of directly coding subblocks into subframes. ๐ฎ These combinations are possible:
- Independent. All channels are coded independently. ๐ฆ All non-stereo files MUST be encoded this way. ๐ โโ๏ธ
- Mid-side. A left and right subblock are converted to mid and side subframes. ๐ธ To calculate a sample for a mid subframe, the corresponding left and right samples are summed, and the result is shifted right by 1 bit. โจ To calculate a sample for a side subframe, the corresponding right sample is subtracted from the corresponding left sample. ๐ง On decoding, all mid channel samples have to be shifted left by 1 bit. ๐ Also, if a side channel sample is odd, 1 has to be added to the corresponding mid channel sample after it has been shifted left by 1 bit. ๐ To reconstruct the left channel, the corresponding samples in the mid and side subframes are added and the result shifted right by 1 bit. ๐ For the right channel, the side channel has to be subtracted from the mid channel and the result shifted right by 1 bit. ๐ Math but make it cute. ๐
- Left-side. The left subblock is coded, and the left and right subblocks are used to code a side subframe. ๐ง The side subframe is constructed the same way as for mid-side. ๐ซถ To decode, the right subblock is restored by subtracting the samples in the side subframe from the corresponding samples in the left subframe. ๐
- Side-right. The left and right subblocks are used to code a side subframe, and the right subblock is coded. ๐ The side subframe is constructed the same way as for mid-side. ๐ฆ To decode, the left subblock is restored by adding the samples in the side subframe to the corresponding samples in the right subframe. ๐ฅ
The side channel needs one extra bit of bit depth, because the subtraction can produce sample values twice as large as the maximum possible in any given bit depth. ๐ญ The mid channel in mid-side stereo doesn't need one extra bit, since it gets shifted right 1 bit. ๐ธ The right shift of the mid channel doesn't cause lossy behavior, because an odd sample in the mid subframe must always be accompanied by a corresponding odd sample in the side subframe. ๐ That means the lost least-significant bit can be restored by taking it from the sample in the side subframe. โจ Bit-perfect and iconic. ๐
4.3. Prediction ๐ฎ
okay so FLAC has four ways to model the input signal, and I'm obsessed with all of them ๐ญ
- Verbatim. Samples are stored directly, no modeling at all ๐ฆ. This is for inputs with little correlation. The raw signal doesn't go through the residual coding stage (it gets slapped into the stream "verbatim"), so this is NOT the same as a zero-order fixed predictor ๐ โโ๏ธ.
- Constant. Just one sample value gets stored ๐ . This is for pure DC ("digital silence"), aka a constant value the whole way through ๐คซ.
- Fixed predictor. Samples get predicted by one of five fixed (predefined) predictors, and whatever error is left goes to the residual coder ๐ฏ. These are super good at simple waveforms โจ. Because they're fixed, no predictor coefficients get stored, which is so iconic ๐. Mathematically, they work by extrapolating the signal from the previous samples ๐ง . The number of previous samples used equals the predictor order. For more info, see Section 9.2.5 ๐ธ.
- Linear predictor. Samples get predicted from past samples plus a set of predictor coefficients, and the error goes to the residual coder ๐ฆ. Ngl, this one adds overhead compared to a fixed predictor, because the coefficients have to be stored ๐. So it's best for more complex waveforms, where the extra overhead is worth it because the residual coding stage ends up with way fewer bits thanks to more accurate prediction ๐. A linear predictor in FLAC has two parameters on top of the coefficients and predictor order: the number of bits each coefficient is stored with (the coefficient precision), and a prediction right shift ๐. The prediction is the sum of each predictor coefficient multiplied by its matching past sample, then divided by applying that right shift โจ. For more info, see Section 9.2.6 ๐.
A FLAC encoder is free to pick any of the above methods to model the input ๐ซถ. BUT, to keep coding lossless, these exceptions apply:
- When the samples that need storing don't all share the same value (aka the signal isn't constant), a constant subframe can't be used ๐ซ.
- When an encoder can't find a fixed or linear predictor where every residual sample fits in a 32-bit signed integer (as described in Section 9.2.7), a verbatim subframe gets used ๐.
For more on fixed and linear predictors, see [Lossless-Compression] and [Robinson-TR156] ๐.
4.4. Residual Coding ๐ง
If a subframe uses a predictor to approximate the audio signal, a residual gets stored to "correct" the approximation to the exact value ๐ง. When an effective predictor is used, the average numerical value of the residual samples is smaller than the samples before prediction ๐. Even so, a few "outlier" residual samples can be way bigger than any of the original samples ๐ณ. Sometimes these outliers even go past the range the original audio's bit depth allows ๐.
To code this kind of stream efficiently (lots of small numbers with the occasional outlier), FLAC uses Rice coding, which is a subset of Golomb coding ๐. Depending on how small the numbers are, a Rice parameter gets chosen ๐ฏ. Each residual sample gets split into two parts by dividing it by 2^(Rice parameter), which makes a quotient and a remainder โ๏ธ. The quotient is stored in unary form and the remainder in binary form ๐ข. If most residual samples are close to zero and a suitable Rice parameter is picked, this variable-length code uses fewer bits than the residual in unencoded form ๐ฆ.
Rice codes can only handle unsigned numbers, so signed numbers get zigzag encoded into a so-called folded residual ๐. See Section 9.2.7 for a more thorough explanation ๐.
The optimal Rice parameter often changes over the course of a subframe ๐. To handle that, the residual can be split into partitions, and each partition gets its own Rice parameter ๐. To keep overhead and complexity low, the number of partitions in a subframe is limited to powers of two ๐.
FLAC uses two forms of Rice coding, which only differ in how many bits encode the Rice parameter: either 4 or 5 bits ๐.
5. Format Principles ๐
FLAC has no format version information, BUT it does have reserved space in several places ๐ธ. Future versions of the format MAY use this reserved space safely without breaking older streams ๐ฎ. Older decoders MAY choose to abort decoding when they hit data encoded with methods they don't recognize ๐. Apart from reserved patterns, the format specifies forbidden patterns in certain places, which means those patterns MUST NOT appear in any bitstream ๐ซ. They're listed in the table below ๐.
+=========================================+=============+
| Description | Reference |
+=========================================+=============+
| Metadata block type 127 | Section 8.1 |
+-----------------------------------------+-------------+
| Minimum and maximum block sizes smaller | Section 8.2 |
| than 16 in streaminfo metadata block | |
+-----------------------------------------+-------------+
| Sample rate bits 0b1111 | Section |
| | 9.1.2 |
+-----------------------------------------+-------------+
| Uncommon block size 65536 | Section |
| | 9.1.6 |
+-----------------------------------------+-------------+
| Predictor coefficient precision bits | Section |
| 0b1111 | 9.2.6 |
+-----------------------------------------+-------------+
| Negative predictor right shift | Section |
| | 9.2.6 |
+-----------------------------------------+-------------+
Table 1All numbers in a FLAC bitstream are integers ๐ข. There are NO floating-point representations, so no decimals sneaking in ๐ โโ๏ธ. All numbers are big-endian coded, EXCEPT the field lengths used in Vorbis comments (see Section 8.6), which are little-endian coded ๐ง. That exception exists to keep as much commonality as possible with Vorbis comments as used by the Vorbis codec (see [Vorbis]) ๐ค. All numbers are unsigned EXCEPT linear predictor coefficients, the linear prediction shift (see Section 9.2.6), and numbers that directly represent samples, which are signed โญ. None of these restrictions apply to application metadata blocks or to Vorbis comment field contents ๐.
All samples encoded to and decoded from the FLAC format MUST be in a signed representation ๐. Honestly, this is the big one ๐ค.
There are several ways to convert unsigned sample representations to signed ones, but FLAC's coding methods work best on samples centered around zero, meaning no DC offset ๐ฏ. In most unsigned audio formats, signals are centered halfway within the range of the unsigned integer type used ๐ฆ. If that's your situation, converting first means copying the number to a signed integer with a big enough range, then subtracting half the range of the unsigned integer type. That gives you a signal with samples centered around 0 โจ.
Unary coding in a FLAC bitstream is done with zero bits terminated by a one bit. For example, the number 5 is coded unary as 0b000001 ๐ธ. This stops the frame sync code from ever showing up inside unary-coded numbers ๐.
When a FLAC file contains data that is forbidden or otherwise not valid, decoder behavior is left unspecified ๐คทโโ๏ธ. A decoder MAY choose to stop decoding upon hitting such data ๐. Examples of such data include:
- One or more decoded sample values go past the range the bit depth allows for that frame. For example, in a frame with a bit depth of 8 bits, any samples outside the inclusive range from
-128to127are NOT valid ๐ฌ. - The number of wasted bits (see Section 9.2.2) used by a subframe is such that the bit depth of that subframe (see Section 9.2.3 for a description of subframe bit depth) equals zero or is negative ๐ซ .
- A frame header Cyclic Redundancy Check (CRC) (see Section 9.1.8) or frame footer CRC (see Section 9.3) doesn't validate โ.
- One of the forbidden bit patterns described in Table 1 gets used ๐จ.
- Format Layout Overview โจ
Okay so, a FLAC bitstream starts with the fLaC marker (that's 0x664C6143 in hex ๐) at the very beginning of the stream. Right after that comes a mandatory metadata block called the streaminfo metadata block, then any number of other metadata blocks, and then the audio frames. Streaminfo is NOT optional, bestie, it's the main character ๐
FLAC supports 127 kinds of metadata blocks, but right now only 7 kinds are actually defined, and you can read about them in Section 8. The other ones are just waiting for their moment ๐ฆ
Now the audio data. It's made of one or more audio frames, and each frame is its own little package ๐ฆ It has a frame header with a sync code, info about the frame (like block size, sample rate, and number of channels), and an 8-bit CRC. The header also includes either the sample number of the first sample in the frame (for variable block size streams) or the frame number (for fixed block size streams). That's what makes fast, sample-accurate seeking possible, and it's giving precision ๐ฏ
After the frame header come the encoded subframes, one for each channel. Then the frame gets zero-padded out to a byte boundary and finished off with a frame footer that holds a checksum for the frame. Each subframe has its own header that says how that subframe was encoded, so it's all very organized ๐
Now here's a cute bit. Every frame starts with a byte-aligned 15-bit sync code, so a decoder can jump in anywhere in the stream ๐ง BUT, ngl, there's no guarantee the sync code doesn't show up somewhere else in the frame. So the decoder has to double-check that it synced correctly by parsing the rest of the frame header and validating the frame header CRC. Not me double-checking everything ๐
Also, a decoder should be able to start decoding at any spot even if it hasn't received a streaminfo metadata block yet. So each frame header carries some basic stream info too: sample rate, bits per sample, number of channels, and so on. The frame header is overhead, so it affects the compression ratio, and FLAC wants it as small as possible ๐ To do that, FLAC uses lookup tables for the most common values of frame properties. When a property isn't in the lookup table, the decoder is pointed to the end of the frame header or to the streaminfo metadata block to find its value (for example, the sample rate). If a frame header refers to the streaminfo metadata block, the file is NOT "streamable", and you can read the details in Section 7 ๐ธ Using lookup tables keeps the file streamable and the frame header small for the most common kinds of audio data, which is the whole vibe ๐
Last thing: the individual subframes (one for each channel) are coded separately within a frame and show up one after another in the stream. So the encoded audio data is NOT channel-interleaved. That keeps decoder complexity down, but the tradeoff is that decode buffers need to be larger ๐ Each subframe has its own header with its attributes, like prediction method and order, residual coding parameters, and so on. Each subframe header is followed by the encoded audio data for that channel โจ
7. Streamable Subset ๐
Okay, so FLAC defines a subset of itself called the FLAC streamable subset. The point is to make sure any stream encoded under this subset is truly "streamable", meaning a decoder that can't seek can still jump into the middle of the stream and start decoding ๐ฆ It also makes hardware decoders more practical, because by limiting the encoding parameters, decoder buffer sizes and other resource requirements can be easily figured out. Main character energy for hardware ๐
The streamable subset puts the following limits on what MAY be used in the stream:
- The sample rate bits (see Section 9.1.2) in the frame header MUST be 0b0001-0b1110, i.e., the frame header MUST NOT refer to the streaminfo metadata block to describe the sample rate. ๐ธ
- The bit depth bits (see Section 9.1.4) in the frame header MUST be 0b001-0b111, i.e., the frame header MUST NOT refer to the streaminfo metadata block to describe the bit depth. ๐
- The stream MUST NOT contain blocks with more than 16384 interchannel samples, i.e., the maximum block size must not be larger than 16384. ๐
- Audio with a sample rate less than or equal to 48000 Hz MUST NOT be contained in blocks with more than 4608 interchannel samples, i.e., the maximum block size used for this audio must not be larger than 4608. ๐ง
- Linear prediction subframes (see Section 9.2.6) containing audio with a sample rate less than or equal to 48000 Hz MUST have a predictor order less than or equal to 12, i.e., the subframe type bits in the subframe header (see Section 9.2.1) MUST NOT be 0b101100-0b111111. ๐
- The Rice partition order (see Section 9.2.7) MUST be less than or equal to 8. โญ
- The channel ordering MUST be equal to one defined in Section 9.1.3, i.e., the FLAC file MUST NOT need a WAVEFORMATEXTENSIBLE_CHANNEL_MASK tag to describe the channel ordering. See Section 8.6.2 for details. ๐
8. File-Level Metadata ๐
Okay, at the start of a FLAC file or stream, right after the fLaC ASCII file signature, one or more metadata blocks MUST be present before any audio frames show up. And the very first metadata block MUST be a streaminfo metadata block. No skipping that, periodt ๐
8.1. Metadata Block Header ๐ฆ
Every metadata block starts with a 4-byte header. The first bit in this header flags whether the metadata block is the last one. It's 0 when other metadata blocks follow, and 1 otherwise. The 7 remaining bits of the first header byte hold the type of the metadata block as an unsigned number between 0 and 126, according to the table below. A value of 127 (i.e., 0b1111111) is forbidden, because it would be confused with a frame sync code ๐ The three bytes that follow code the size of the metadata block in bytes, excluding the 4 header bytes, as an unsigned number coded big-endian ๐
+=========+=======================================================+
| Value | Metadata Block Type |
+=========+=======================================================+
| 0 | Streaminfo |
+---------+-------------------------------------------------------+
| 1 | Padding |
+---------+-------------------------------------------------------+
| 2 | Application |
+---------+-------------------------------------------------------+
| 3 | Seek table |
+---------+-------------------------------------------------------+
| 4 | Vorbis comment |
+---------+-------------------------------------------------------+
| 5 | Cuesheet |
+---------+-------------------------------------------------------+
| 6 | Picture |
+---------+-------------------------------------------------------+
| 7 - 126 | Reserved |
+---------+-------------------------------------------------------+
| 127 | Forbidden (to avoid confusion with a frame sync code) |
+---------+-------------------------------------------------------+Table 2 ๐ธ
8.2. Streaminfo โจ
Okay so the streaminfo block is basically the stream's cheat sheet ๐๐ It has info about the whole stream, like sample rate, number of channels, total number of samples, etc. It MUST be the very first metadata block in the stream. Other metadata blocks MAY follow it. There MUST be no more than one streaminfo metadata block per FLAC stream, no exceptions ๐ซถ
If the streaminfo block has wrong or incomplete info, what the decoder does is left unspecified, so it's up to whoever built the decoder ๐คทโโ๏ธ A decoder MAY choose to stop decoding when the info turns out to be incorrect or has forbidden values. Also, if a decoder trusts the maximum frame size, maximum block size, number of audio channels, bits per sample, and total number of samples from here without doing more checks while it decodes the audio frames, it could be vulnerable to buffer overflows ๐ญ Dramatic, but real. See also Section 11.
Here's the table that describes the streaminfo block in order. The metadata block header is not included ๐
+========+=================================================+
| Data | Description |
+========+=================================================+
| u(16) | The minimum block size (in samples) used in the |
| | stream, excluding the last block. |
+--------+-------------------------------------------------+
| u(16) | The maximum block size (in samples) used in the |
| | stream. |
+--------+-------------------------------------------------+
| u(24) | The minimum frame size (in bytes) used in the |
| | stream. A value of 0 signifies that the value |
| | is not known. |
+--------+-------------------------------------------------+
| u(24) | The maximum frame size (in bytes) used in the |
| | stream. A value of 0 signifies that the value |
| | is not known. |
+--------+-------------------------------------------------+
| u(20) | Sample rate in Hz. |
+--------+-------------------------------------------------+
| u(3) | (number of channels)-1. FLAC supports from 1 |
| | to 8 channels. |
+--------+-------------------------------------------------+
| u(5) | (bits per sample)-1. FLAC supports from 4 to |
| | 32 bits per sample. |
+--------+-------------------------------------------------+
| u(36) | Total number of interchannel samples in the |
| | stream. A value of 0 here means the number of |
| | total samples is unknown. |
+--------+-------------------------------------------------+
| u(128) | MD5 checksum of the unencoded audio data. This |
| | allows the decoder to determine if an error |
| | exists in the audio data even when, despite the |
| | error, the bitstream itself is valid. A value |
| | of 0 signifies that the value is not known. |
+--------+-------------------------------------------------+Table 3
The minimum block size and the maximum block size MUST be in the 16-65535 range. The minimum block size MUST be equal to or less than the maximum block size.
Any frame but the last one MUST have a block size equal to or greater than the minimum block size, and MUST have a block size equal to or less than the maximum block size. The last frame MUST have a block size equal to or less than the maximum block size. It doesn't have to follow the minimum block size, because the block size of that frame must be able to fit all the audio data the stream contains ๐
If the minimum block size is equal to the maximum block size, the file contains a fixed block size stream, since the minimum block size leaves out the last block. Heads up, though: in a stream with a variable block size, the actual maximum block size MAY be smaller than the maximum block size listed in the streaminfo block, and the actual smallest block size, leaving out the last block, MAY be larger than the minimum block size listed there. Why? The encoder has to write these fields before it gets any input audio data, so it can't know ahead of time which block sizes it'll use. It only knows the bounds they'll be picked between ๐ฆ
The sample rate MUST NOT be 0 when the FLAC file contains audio. A sample rate of 0 MAY be used when non-audio is represented. This is handy if the data isn't along a time axis, or if the sample rate of the data is outside the range FLAC can represent in the streaminfo block. If you do use a sample rate of 0, it is recommended to store what the encoded content means in a Vorbis comment field (see Section 8.6) or an application metadata block (see Section 8.4). This document doesn't define that kind of metadata ๐ค
The MD5 checksum is computed by applying the MD5 message-digest algorithm in [RFC1321]. The message fed into this algorithm is all the samples of all channels, interleaved, in signed, little-endian form. The interleaving is per sample. For a stereo file, that means the first sample of the first channel, then the first sample of the second channel, then the second sample of the first channel, and so on ๐ Before computing the checksum, all samples must be byte-aligned. If the bit depth isn't a whole number of bytes, the value of each sample gets sign-extended to the next whole number of bytes.
Here's how the bits line up for a 2-channel stream with 6-bit samples ๐
SSAAAAAASSBBBBBBSSCCCCCC
^ ^ ^ ^ ^ ^
| | | | | Bits of 2nd sample of 1st channel
| | | | Sign extension bits of 2nd sample of 2nd channel
| | | Bits of 1st sample of 2nd channel
| | Sign extension bits of 1st sample of 2nd channel
| Bits of 1st sample of 1st channel
Sign extension bits of 1st sample of 1st channelAnd here's a 1-channel stream with 12-bit samples, lined up in little-endian byte order ๐
AAAAAAAASSSSAAAABBBBBBBBSSSSBBBB
^ ^ ^ ^ ^ ^
| | | | | Most-significant 4 bits of 2nd sample
| | | | Sign extension bits of 2nd sample
| | | Least-significant 8 bits of 2nd sample
| | Most-significant 4 bits of 1st sample
| Sign extension bits of 1st sample
Least-significant 8 bits of 1st sample8.3. Padding ๐งธ
The padding metadata block allows for an arbitrary amount of padding. This is super useful when you know the metadata will get edited after encoding. The user can tell the encoder to reserve a padding block of the right size, so when metadata gets added, it just overwrites the padding (which is relatively quick) instead of getting inserted into the existing file (which would normally mean rewriting the entire file) ๐ฉโจ There MAY be one or more padding metadata blocks per FLAC stream.
+======+======================================================+
| Data | Description |
+======+======================================================+
| u(n) | n "0" bits (n MUST be a multiple of 8, i.e., a whole |
| | number of bytes, and MAY be zero). n is 8 times the |
| | size described in the metadata block header. |
+------+------------------------------------------------------+Table 4
8.4. Application ๐
The application metadata block is for use by third-party applications. The only mandatory field is a 32-bit application identifier, called the application ID. Application IDs are registered in the IANA "FLAC Application Metadata Block IDs" registry (see Section 12.2) ๐๐
+=======+===================================================+
| Data | Description |
+=======+===================================================+
| u(32) | Registered application ID. |
+-------+---------------------------------------------------+
| u(n) | Application data (n MUST be a multiple of 8, |
| | i.e., a whole number of bytes). n is 8 times the |
| | size described in the metadata block header minus |
| | the 32 bits already used for the application ID. |
+-------+---------------------------------------------------+Table 5
8.5. Seek Table ๐
The seek table metadata block can be used to store seek points. You can seek to any given sample in a FLAC stream without a seek table, but the delay can be unpredictable, since the bitrate may vary widely within a stream. Adding seek points to a stream can cut that delay down a lot ๐ There MUST NOT be more than one seek table metadata block in a stream, but the table can have any number of seek points.
Each seek point takes 18 bytes, so a seek table with 1% resolution within a stream adds less than 2 kilobytes of data. The number of seek points is implied by the size described in the metadata block header, i.e., equal to size / 18. There's also a special "placeholder" seek point. Decoders will ignore it, but it can be used to reserve space for inserting future seek points ๐ง
+=============+=============================+
| Data | Description |
+=============+=============================+
| Seek points | Zero or more seek points as |
| | defined in Section 8.5.1. |
+-------------+-----------------------------+Table 6
A seek table is generally not usable for seeking in a FLAC file embedded in a container (see Section 10). That's because containers usually interleave FLAC data with other data, and the offsets used in seek points are the ones from an unmuxed FLAC stream. Also, containers often have their own seeking methods ๐ Still, it's possible to store the seek table in the container along with other metadata when muxing a FLAC file. That way, the stored seek table can be restored when demuxing the FLAC stream into a standalone FLAC file ๐
8.5.1. Seek Point ๐ง
Okay bestie, each seek point is a little three-field package ๐ฆ and here's the whole lineup:
+=======+==========================================================+
| Data | Description |
+=======+==========================================================+
| u(64) | Sample number of the first sample in the target frame or |
| | 0xFFFFFFFFFFFFFFFF for a placeholder point. |
+-------+----------------------------------------------------------+
| u(64) | Offset (in bytes) from the first byte of the first frame |
| | header to the first byte of the target frame's header. |
+-------+----------------------------------------------------------+
| u(16) | Number of samples in the target frame. |
+-------+----------------------------------------------------------+Table 7
Some notes, because you know I'm not skipping the fine print ๐ :
- For placeholder points, the second and third field values are undefined. ๐
- Seek points within a table MUST be sorted in ascending order by sample number. Sorted, no exceptions. ๐
- Seek points within a table MUST be unique by sample number, with the exception of placeholder points. Placeholders are the only ones allowed to be copies. ๐ฏ
- Put those last two notes together and you get this: there MAY be any number of placeholder points, but they MUST all sit at the end of the table. Placeholders at the back, always. ๐ซถ
- The sample offsets are those of an unmuxed FLAC stream. The offsets MUST NOT be updated on muxing to reflect the new offsets of FLAC frames in a container. Don't go rewriting them just because you put the file in a container, periodt ๐ซ
8.6. Vorbis Comment ๐
Okay so a Vorbis comment metadata block holds human-readable info, encoded in UTF-8 ๐. The name comes from the fact that the Vorbis codec stores metadata in almost the same way (see [Vorbis]). The block is a vendor string, optionally followed by a bunch of fields, and each field is a name paired with its contents. The vendor string tells you which program made the file or stream. The fields describe whatever's in the audio. Plenty of people call these "FLAC tags" or just "tags," and honestly that's iconic. A FLAC file MUST NOT contain more than one Vorbis comment metadata block. One is the limit, bestie โจ
Here's how the bytes are laid out. Right after the metadata block header, you get 4 bytes with the length of the vendor string, as an unsigned number in little-endian. Then comes the vendor string itself. It's UTF-8 coded and it isn't terminated in any way, so there's no little null-byte signpost at the end ๐งญ
After the vendor string, there are 4 more bytes holding the number of fields in the Vorbis comment block, again unsigned and little-endian. If that number isn't zero, the fields come next. Each one starts with a 4-byte unsigned little-endian length, followed by the field. Like the vendor string, each field is UTF-8 coded and not terminated in any way ๐ธ
Every field is a field name and field contents, separated by an = character. The field name MUST only consist of UTF-8 code points U+0020 through U+007E, excluding U+003D, which is the = character. Translation: the name can be any printable ASCII character except the equals sign. The evaluation of field names MUST be case insensitive, so U+0041 through 0+005A (A-Z) MUST be considered equivalent to U+0061 through U+007A (a-z). So TITLE and title are the same vibe ๐ The field contents can contain any UTF-8 character at all, which is giving freedom ๐ฆ
Now, the Vorbis comment as used in Vorbis allows for 2^64 bytes of data, whereas the FLAC metadata block is limited to 2^24 bytes. But these comments are meant to be human-readable text, so the FLAC limit is unlikely to actually get in your way ๐ Also, heads up: the 32-bit field lengths are little-endian, which is the opposite of the big-endian vibe the rest of FLAC has going on. Plot twist ๐
8.6.1. Standard Field Names ๐
Only one standard field name is defined: the channel mask field (see Section 8.6.2). Everything else is left open, because a field name only makes sense for the content it describes. Like, names that work for a single music album would be totally useless when labeling archived broadcasts, recordings of any kind, or a whole collection of tracks. Even for one song, the conventions change depending on the genre. Orchestral music does its own thing compared to music by solo artists or bands ๐ถ
Even though no other field names are formally defined, there's a general trend among devices and software that play FLAC for music. Most of them recognize at least these field names:
Title: Name of the current work.Artist: Name of the artist generally responsible for the current work. For orchestral works, this is usually the composer; otherwise, it is often the performer.Album: Name of the collection the current work belongs to.
If you want a bigger list of field names for describing a single work of music across different genres, the MusicBrainz project's tag list is suggested; see [MusicBrainz]. Go explore, it's a whole rabbit hole ๐
8.6.2. Channel Mask ๐
Besides the fields about the work itself, there's one field that's defined for technical reasons: WAVEFORMATEXTENSIBLE_CHANNEL_MASK. It's used to say that the channels in a file are different from the default channels defined in Section 9.1.3. For example, by default a FLAC file with two channels is read as having a left and right channel. With this field, you can describe completely different channel contents ๐ง
The channel mask is made of flag bits, each one showing which channels are present. The flags only tell you which channels exist, not what order they're in. So if a file's channels are ordered differently, they have to be reordered before encoding ๐ The mask is stored as a hexadecimal value with a 0x prefix (check the examples below, they're giving clarity). Also, please note that a file whose channel order is defined through WAVEFORMATEXTENSIBLE_CHANNEL_MASK is not streamable (see Section 7), because that field isn't found in each frame header. The mask bits are in the table below ๐
+============+=============================+
| Bit Number | Channel Description |
+============+=============================+
| 0 | Front left |
+------------+-----------------------------+
| 1 | Front right |
+------------+-----------------------------+
| 2 | Front center |
+------------+-----------------------------+
| 3 | Low-frequency effects (LFE) |
+------------+-----------------------------+
| 4 | Back left |
+------------+-----------------------------+
| 5 | Back right |
+------------+-----------------------------+
| 6 | Front left of center |
+------------+-----------------------------+
| 7 | Front right of center |
+------------+-----------------------------+
| 8 | Back center |
+------------+-----------------------------+
| 9 | Side left |
+------------+-----------------------------+
| 10 | Side right |
+------------+-----------------------------+
| 11 | Top center |
+------------+-----------------------------+
| 12 | Top front left |
+------------+-----------------------------+
| 13 | Top front center |
+------------+-----------------------------+
| 14 | Top front right |
+------------+-----------------------------+
| 15 | Top rear left |
+------------+-----------------------------+
| 16 | Top rear center |
+------------+-----------------------------+
| 17 | Top rear right |
+------------+-----------------------------+Table 8
Here are three examples, because examples are everything โจ
- A file has a single channel, an LFE channel. The Vorbis comment field is
WAVEFORMATEXTENSIBLE_CHANNEL_MASK=0x8. - A file has four channels: front left, front right, top front left, and top front right. The Vorbis comment field is
WAVEFORMATEXTENSIBLE_CHANNEL_MASK=0x5003. - An input has four channels: back center, top front center, front center, and top rear center, in that order. These have to be reordered to front center, back center, top front center, and top rear center. The Vorbis comment field added is
WAVEFORMATEXTENSIBLE_CHANNEL_MASK=0x12104.
WAVEFORMATEXTENSIBLE_CHANNEL_MASK fields MAY be padded with zeros, for example 0x0008 for a single LFE channel. Parsing of WAVEFORMATEXTENSIBLE_CHANNEL_MASK fields MUST be case-insensitive for both the field name and the field contents. Both the name and the value get the same chill treatment ๐ซถ
A WAVEFORMATEXTENSIBLE_CHANNEL_MASK field of 0x0 can be used to say that none of the audio channels in a file line up with speaker positions. That happens when the audio needs to be decoded into speaker positions (like Ambisonics B-format audio), or when a multitrack recording is in the file ๐๏ธ
It's also possible for the field to code for fewer channels than the audio actually has. If that's the case, the remaining channels SHOULD NOT be rendered by a playback application that doesn't know what they're for. Like, the Ambisonics UHJ format works on stereo gear: its first two channels can play back on stereo equipment, but all four channels together can decode into surround sound. For that example, the Vorbis comment field WAVEFORMATEXTENSIBLE_CHANNEL_MASK=0x3 would be set, meaning the first two channels are front left and front right, and the other channels don't line up with speaker positions directly. Two-channel mask, zero drama ๐ง๐
If audio channels that aren't assigned to any speaker are contained, and decoding to speaker positions is possible, it is recommended to provide metadata on how that decoding should take place in another Vorbis comment field or an application metadata block. This document does not define such metadata. So if you need it, you'll have to bring your own ๐ซ
8.7. Cuesheet ๐ฟโจ
okay bestie, the cuesheet block is giving CD energy ๐ฟ It can either store the track and index point structure of a Compact Disc Digital Audio (CD-DA) along with its audio, or it can just mark locations of interest inside a FLAC file ๐ฆ Some of this comes straight from the CD-DA spec (aka Red Book), which is standardized as [IEC.60908.1999]. ngl, you don't have to go read that doc, because everything you need to implement this block is right here ๐
here's the layout, obsessed ๐ญ
+============+======================================================+
| Data | Description |
+============+======================================================+
| u(128*8) | Media catalog number in ASCII |
| | printable characters 0x20-0x7E. |
+------------+------------------------------------------------------+
| u(64) | Number of lead-in samples. |
+------------+------------------------------------------------------+
| u(1) | 1 if the cuesheet corresponds to a |
| | CD-DA; else 0. |
+------------+------------------------------------------------------+
| u(7+258*8) | Reserved. All bits MUST be set to |
| | zero. |
+------------+------------------------------------------------------+
| u(8) | Number of tracks in this cuesheet. |
+------------+------------------------------------------------------+
| Cuesheet | A number of structures as specified |
| tracks | in Section 8.7.1 equal to the number |
| | of tracks specified previously. |
+------------+------------------------------------------------------+
Table 9if the media catalog number is less than 128 bytes long, it gets right-padded with 0x00 bytes ๐ for CD-DA, that means a 13-digit number followed by 115 0x00 bytes.
the number of lead-in samples only has meaning for CD-DA cuesheets. for other uses, it should be 0 ๐ง for CD-DA, the lead-in is the TRACK 00 area where the table of contents is stored. more precisely, it's the number of samples from the first sample of the media to the first sample of the first index point of the first track. according to [IEC.60908.1999], the lead-in MUST be silent, and CD grabbing software doesn't usually store it ๐ on top of that, the lead-in MUST be at least two seconds but MAY be longer. so the lead-in length gets stored here, which is how the absolute position of the first track can be computed ๐งฎ also, the number of samples runs up to the first index point of the first track, not necessarily to INDEX 01 of the first track, because even the first track MAY have INDEX 00 data. main character energy ๐
the number of tracks MUST be at least 1, because a cuesheet block MUST have a lead-out track ๐ for CD-DA, this number MUST be no more than 100 (99 regular tracks and one lead-out track). the lead-out track is always the last track in the cuesheet. for CD-DA, the lead-out track number MUST be 170 as specified by [IEC.60908.1999]. otherwise, it MUST be 255 ๐ธ
8.7.1. Cuesheet Track ๐ฆ
here's the track layout, it's giving organized ๐ซถ
+=============+=====================================================+
| Data | Description |
+=============+=====================================================+
| u(64) | Track offset of the first index point in |
| | samples, relative to the beginning of the |
| | FLAC audio stream. |
+-------------+-----------------------------------------------------+
| u(8) | Track number. |
+-------------+-----------------------------------------------------+
| u(12*8) | Track ISRC. |
+-------------+-----------------------------------------------------+
| u(1) | The track type: 0 for audio, 1 for non-audio. |
| | This corresponds to the CD-DA Q-channel |
| | control bit 3. |
+-------------+-----------------------------------------------------+
| u(1) | The pre-emphasis flag: 0 for no pre-emphasis, |
| | 1 for pre-emphasis. This corresponds to the |
| | CD-DA Q-channel control bit 5. |
+-------------+-----------------------------------------------------+
| u(6+13*8) | Reserved. All bits MUST be set to zero. |
+-------------+-----------------------------------------------------+
| u(8) | The number of track index points. |
+-------------+-----------------------------------------------------+
| Cuesheet | For all tracks except the lead-out track, a |
| track index | number of structures as specified in |
| points | Section 8.7.1.1 equal to the number of index |
| | points specified previously. |
+-------------+-----------------------------------------------------+
Table 10the track offset is a little different from CD-DA ๐ over there, the track's offset in the table of contents (TOC) is that of the track's INDEX 01, even if there's an INDEX 00. for CD-DA, the track offset MUST be evenly divisible by 588 samples (588 samples = 44100 samples/s * 1/75 s) โจ
a track number of 0 is not allowed, because the CD-DA spec reserves that one for the lead-in ๐ซ for CD-DA, the number MUST be 1-99 or 170 for the lead-out. for non-CD-DA, the track number MUST be 255 for the lead-out. it is recommended to start with track 1 and increase sequentially ๐ข and track numbers MUST be unique within a cuesheet, no copies allowed ๐ โโ๏ธ
the track ISRC (International Standard Recording Code) is a 12-digit alphanumeric code, and you can check [ISRC-handbook] for the deets ๐ถ a value of 12 ASCII 0x00 characters MAY be used to denote the absence of an ISRC.
there MUST be at least one index point in every track in a cuesheet, except for the lead-out track, which MUST have zero. for CD-DA, the number of index points MUST NOT be more than 100 ๐
8.7.1.1. Cuesheet Track Index Point ๐
+========+====================================+
| Data | Description |
+========+====================================+
| u(64) | Offset in samples, relative to the |
| | track offset, of the index point. |
+--------+------------------------------------+
| u(8) | The track index point number. |
+--------+------------------------------------+
| u(3*8) | Reserved. All bits MUST be set to |
| | zero. |
+--------+------------------------------------+
Table 11last one for this section, and it's a cute one ๐ for CD-DA, the track index point offset MUST be evenly divisible by 588 samples (588 samples = 44100 samples/s * 1/75 s). note that the offset is measured from the beginning of the track, not the beginning of the audio data ๐ฅน
for CD-DA, a track index point number of 0 corresponds to the track pre-gap โญ the first index point in a track MUST have a number of 0 or 1, and after that, index point numbers MUST increase by 1. index point numbers MUST be unique within a track. the numbering has to stay consistent or the vibes are off ๐ ๐ฅ
8.8. Picture โจ
okay so the picture metadata block is where the FLAC file stores an image that belongs to the audio, like album art ๐ผ๏ธ๐. The format is borrowed from the Attached Picture (APIC) frame in ID3v2, see [ID3v2]. ngl the big difference is that instead of ID3v2's 0x00 delimited strings, the media type and description get a 4-byte length field in front of them ๐ . A FLAC file MAY contain one or more picture metadata blocks, so you can stack up the art ๐
Bestie, the length fields are 4 bytes, so in theory they could describe up to 4 GiB ๐ญ but the whole metadata block still can't be bigger than what the metadata block header can describe, which is 16 MiB. So no 4 GiB pictures, sorry not sorry ๐
Instead of actual picture data, the block can also hold a URI as described in [RFC3986]. Pointing at the image instead of embedding it, very efficient, very main character ๐ฆ
Here's how the structure of a picture metadata block is laid out:
+========+==========================================================+
| Data | Description |
+========+==========================================================+
| u(32) | The picture type according to Table 13. |
+--------+----------------------------------------------------------+
| u(32) | The length of the media type string in bytes. |
+--------+----------------------------------------------------------+
| u(n*8) | The media type string as specified by [RFC2046], |
| | or the text string --> to signify that the data |
| | part is a URI of the picture instead of the |
| | picture data itself. This field must be in |
| | printable ASCII characters 0x20-0x7E. |
+--------+----------------------------------------------------------+
| u(32) | The length of the description string in bytes. |
+--------+----------------------------------------------------------+
| u(n*8) | The description of the picture in UTF-8. |
+--------+----------------------------------------------------------+
| u(32) | The width of the picture in pixels. |
+--------+----------------------------------------------------------+
| u(32) | The height of the picture in pixels. |
+--------+----------------------------------------------------------+
| u(32) | The color depth of the picture in bits per |
| | pixel. |
+--------+----------------------------------------------------------+
| u(32) | For indexed-color pictures (e.g., GIF), the |
| | number of colors used; 0 for non-indexed |
| | pictures. |
+--------+----------------------------------------------------------+
| u(32) | The length of the picture data in bytes. |
+--------+----------------------------------------------------------+
| u(n*8) | The binary picture data. |
+--------+----------------------------------------------------------+Table 12
Okay, the width, height, color depth, and "number of colors" fields are for informational purposes only ๐ Applications MUST NOT use them to decode the picture or to decide how to display it. But applications MAY use them to decide whether or not to process a block (like when they're picking between different picture blocks), and MAY show them to the user. And if a field doesn't make sense for the picture (vector images don't really have pixel width or height, for example) or the content of a field is unknown, that field MUST be set to zero ๐ง
Next up, the picture types. Values that aren't listed are reserved, and there MAY only be one each of picture types 1 and 2 in a file. In general practice, lots of FLAC playback devices and software show the picture metadata block, if there is one, with picture type 3 (front cover) during playback ๐
+=======+=================================================+
| Value | Picture Type |
+=======+=================================================+
| 0 | Other |
+-------+-------------------------------------------------+
| 1 | PNG file icon of 32x32 pixels (see [RFC2083]) |
+-------+-------------------------------------------------+
| 2 | General file icon |
+-------+-------------------------------------------------+
| 3 | Front cover |
+-------+-------------------------------------------------+
| 4 | Back cover |
+-------+-------------------------------------------------+
| 5 | Liner notes page |
+-------+-------------------------------------------------+
| 6 | Media label (e.g., CD, Vinyl or Cassette label) |
+-------+-------------------------------------------------+
| 7 | Lead artist, lead performer, or soloist |
+-------+-------------------------------------------------+
| 8 | Artist or performer |
+-------+-------------------------------------------------+
| 9 | Conductor |
+-------+-------------------------------------------------+
| 10 | Band or orchestra |
+-------+-------------------------------------------------+
| 11 | Composer |
+-------+-------------------------------------------------+
| 12 | Lyricist or text writer |
+-------+-------------------------------------------------+
| 13 | Recording location |
+-------+-------------------------------------------------+
| 14 | During recording |
+-------+-------------------------------------------------+
| 15 | During performance |
+-------+-------------------------------------------------+
| 16 | Movie or video screen capture |
+-------+-------------------------------------------------+
| 17 | A bright colored fish |
+-------+-------------------------------------------------+
| 18 | Illustration |
+-------+-------------------------------------------------+
| 19 | Band or artist logotype |
+-------+-------------------------------------------------+
| 20 | Publisher or studio logotype |
+-------+-------------------------------------------------+Table 13
Value 17 ("A bright colored fish") ๐ is a mystery, honestly. Its origin and use are unclear. It got copied over to keep compatibility with ID3v2, and applications are discouraged from offering it to users when they embed a picture. Lowkey a whole vibe, but not one we're pushing ๐ญ
If the block holds a URI (not an actual picture), a few points apply:
- The URI can be in either absolute or relative form. If it's relative, it's related to the URI of the FLAC content being processed.
- Applications MUST obtain explicit user approval to retrieve images via remote protocols, and also to retrieve local images that aren't located in the same directory as the FLAC file being processed. No sneaky fetching, periodt ๐
- Applications supporting linked images MUST handle unavailability of URIs gracefully. They MAY report that unavailability to the user.
- Applications MAY reject processing URIs for any reason, particularly for security or privacy reasons. Protect your vibe ๐ซถ
9. Frame Structure โจ
One or more frames follow directly after the last metadata block ๐ถ Each frame is made of a frame header, one or more subframes, padding zero bits to get to byte alignment, and a frame footer. The number of subframes in each frame equals the number of audio channels.
Each frame header stores the audio sample rate, number of bits per sample, and number of channels on its own, independently of the streaminfo metadata block and other frame headers. This was done to permit multicasting of FLAC files, but it also means these properties can change mid-stream ๐ฆ Since not every environment where FLAC decoders run can cope with those properties changing during playback, a decoder MAY choose to stop decoding when that happens. A decoder that doesn't check for such a change could be vulnerable to buffer overflows ๐ See also Section 11.
Note that storing audio with changing properties in FLAC causes various practical problems. For example, these changes have to happen on a frame boundary or the process won't be lossless. If a variable block size is used to make that work, blocks smaller than 16 samples are not allowed, so it's not possible to store an audio stream where these properties change within 16 samples of the last change or the start of the file. Also, the streaminfo metadata block can only hold a single set of properties, so it's only valid for part of such an audio stream. Instead, it is RECOMMENDED to store an audio stream with changing properties in FLAC encapsulated in a container that can handle those changes, since containers don't suffer from the limitations mentioned above. See Section 10 for details ๐ธ
9.1. Frame Header
Each frame MUST start on a byte boundary and begin with the 15-bit frame sync code 0b111111111111100. Right after the sync code comes the blocking strategy bit, which MUST NOT change during the audio stream. The blocking strategy bit is 0 for a fixed block size stream or 1 for a variable block size stream. If the blocking strategy is known, a decoder can include this bit when searching for the start of a frame, which cuts down the chance of a false positive, since the first two bytes of a frame are either 0xFFF8 for a fixed block size stream or 0xFFF9 for a variable block size stream ๐ฅ
9.1.1. Block Size Bits โจ
Okay bestie, right after the frame sync code and the blocking strategy bit come 4 bits (the first 4 bits of the third byte of each frame) called the block size bits ๐ Their value tells you the block size, using the table below, where v is the value of those 4 bits read as an unsigned number ๐ If the block size bits point to an uncommon block size, that size gets stored after the coded number, see Section 9.1.6 ๐ฆ
+=================+=============================================+
| Value | Block Size |
+=================+=============================================+
| 0b0000 | Reserved |
+-----------------+---------------------------------------------+
| 0b0001 | 192 |
+-----------------+---------------------------------------------+
| 0b0010 - 0b0101 | 144 * (2^v), i.e., 576, 1152, 2304, or 4608 |
+-----------------+---------------------------------------------+
| 0b0110 | Uncommon block size minus 1, stored as an |
| | 8-bit number |
+-----------------+---------------------------------------------+
| 0b0111 | Uncommon block size minus 1, stored as a |
| | 16-bit number |
+-----------------+---------------------------------------------+
| 0b1000 - 0b1111 | 2^v, i.e., 256, 512, 1024, 2048, 4096, |
| | 8192, 16384, or 32768 |
+-----------------+---------------------------------------------+
Table 149.1.2. Sample Rate Bits ๐ธ
Next up are 4 more bits (the last 4 bits of the third byte of each frame), and these are the sample rate bits ๐ง They tell you the sample rate of the audio, using the table below. If they code for an uncommon sample rate, that gets stored after the uncommon block size. If no uncommon block size was used, it goes after the coded number instead. See Section 9.1.7 ๐
+========+==========================================================+
| Value | Sample Rate |
+========+==========================================================+
| 0b0000 | Sample rate only stored in the |
| | streaminfo metadata block |
+--------+----------------------------------------------------------+
| 0b0001 | 88.2 kHz |
+--------+----------------------------------------------------------+
| 0b0010 | 176.4 kHz |
+--------+----------------------------------------------------------+
| 0b0011 | 192 kHz |
+--------+----------------------------------------------------------+
| 0b0100 | 8 kHz |
+--------+----------------------------------------------------------+
| 0b0101 | 16 kHz |
+--------+----------------------------------------------------------+
| 0b0110 | 22.05 kHz |
+--------+----------------------------------------------------------+
| 0b0111 | 24 kHz |
+--------+----------------------------------------------------------+
| 0b1000 | 32 kHz |
+--------+----------------------------------------------------------+
| 0b1001 | 44.1 kHz |
+--------+----------------------------------------------------------+
| 0b1010 | 48 kHz |
+--------+----------------------------------------------------------+
| 0b1011 | 96 kHz |
+--------+----------------------------------------------------------+
| 0b1100 | Uncommon sample rate in kHz, |
| | stored as an 8-bit number |
+--------+----------------------------------------------------------+
| 0b1101 | Uncommon sample rate in Hz, stored |
| | as a 16-bit number |
+--------+----------------------------------------------------------+
| 0b1110 | Uncommon sample rate in Hz divided |
| | by 10, stored as a 16-bit number |
+--------+----------------------------------------------------------+
| 0b1111 | Forbidden |
+--------+----------------------------------------------------------+
Table 159.1.3. Channels Bits ๐ฆ
The next 4 bits (the first 4 bits of the fourth byte of each frame) are the channels bits, and they hold both the number of audio channels and any stereo decorrelation that's been used, per the table below ๐ฉท
If you're using a channel layout that isn't in the table, you can signal it with a WAVEFORMATEXTENSIBLE_CHANNEL_MASK tag in a Vorbis comment metadata block, see Section 8.6.2 for details ๐ Even if you use a different layout with WAVEFORMATEXTENSIBLE_CHANNEL_MASK and override the channel ordering in the table, the channels bits still hold the actual number of channels coded in the frame ๐ซถ For how left-side, side-right, and mid-side stereo are coded, check Section 4.2 ๐
+==========+====================================================+
| Value | Channels |
+==========+====================================================+
| 0b0000 | 1 channel: mono |
+----------+----------------------------------------------------+
| 0b0001 | 2 channels: left, right |
+----------+----------------------------------------------------+
| 0b0010 | 3 channels: left, right, center |
+----------+----------------------------------------------------+
| 0b0011 | 4 channels: front left, front right, back left, |
| | back right |
+----------+----------------------------------------------------+
| 0b0100 | 5 channels: front left, front right, front center, |
| | back/surround left, back/surround right |
+----------+----------------------------------------------------+
| 0b0101 | 6 channels: front left, front right, front center, |
| | LFE, back/surround left, back/surround right |
+----------+----------------------------------------------------+
| 0b0110 | 7 channels: front left, front right, front center, |
| | LFE, back center, side left, side right |
+----------+----------------------------------------------------+
| 0b0111 | 8 channels: front left, front right, front center, |
| | LFE, back left, back right, side left, side right |
+----------+----------------------------------------------------+
| 0b1000 | 2 channels: left, right; stored as left-side |
| | stereo |
+----------+----------------------------------------------------+
| 0b1001 | 2 channels: left, right; stored as side-right |
| | stereo |
+----------+----------------------------------------------------+
| 0b1010 | 2 channels: left, right; stored as mid-side stereo |
+----------+----------------------------------------------------+
| 0b1011 - | Reserved |
| 0b1111 | |
+----------+----------------------------------------------------+
Table 169.1.4. Bit Depth Bits ๐
The next 3 bits (bits 5, 6, and 7 of each fourth byte of each frame) hold the bit depth of the audio, per the table below ๐ The bit right after those is reserved and MUST be zero, so keep it at zero ๐
+=======+========================================================+
| Value | Bit Depth |
+=======+========================================================+
| 0b000 | Bit depth only stored in the streaminfo metadata block |
+-------+--------------------------------------------------------+
| 0b001 | 8 bits per sample |
+-------+--------------------------------------------------------+
| 0b010 | 12 bits per sample |
+-------+--------------------------------------------------------+
| 0b011 | Reserved |
+-------+--------------------------------------------------------+
| 0b100 | 16 bits per sample |
+-------+--------------------------------------------------------+
| 0b101 | 20 bits per sample |
+-------+--------------------------------------------------------+
| 0b110 | 24 bits per sample |
+-------+--------------------------------------------------------+
| 0b111 | 32 bits per sample |
+-------+--------------------------------------------------------+
Table 179.1.5. Coded Number ๐ธ
Okay bestie, right after the reserved bit (starting at the fifth byte of the frame) you get either a sample number or a frame number, and we call that the coded number ๐ If you're dealing with a variable block size stream, the sample number of the very first sample in the frame is what gets encoded. If the file has a fixed block size stream instead, it's the frame number that gets encoded โจ To tell which kind you've got, peep Section 9.1 and the blocking strategy bit, which signals fixed versus variable block size. If you want more deets, see also Appendix B.1 ๐ฆ
The coded number lives in a variable-length code that's basically UTF-8 from [RFC3629], just stretched so it can hold up to 36 bits unencoded or 7 bytes encoded ๐ง
When a frame number is encoded, the value MUST NOT be larger than what fits in 31 bits unencoded or 6 bytes encoded ๐ Please note (this part matters!!) that most general purpose UTF-8 encoders and decoders follow [RFC3629], so they won't be able to handle these extended codes ๐ Also, UTF-8 is made specifically for encoding characters, but FLAC uses it to encode numbers instead ๐ฅ So to encode or decode a coded number, follow the procedures in Section 3 of [RFC3629], except instead of a character number you use a frame or sample number. And use the extended table below instead of the table in Section 3 of [RFC3629] ๐
+============================+=====================================+
| Number Range (Hexadecimal) | Octet Sequence (Binary) |
+============================+=====================================+
| 0000 0000 0000 - | 0xxxxxxx |
| 0000 0000 007F | |
+----------------------------+-------------------------------------+
| 0000 0000 0080 - | 110xxxxx 10xxxxxx |
| 0000 0000 07FF | |
+----------------------------+-------------------------------------+
| 0000 0000 0800 - | 1110xxxx 10xxxxxx 10xxxxxx |
| 0000 0000 FFFF | |
+----------------------------+-------------------------------------+
| 0000 0001 0000 - | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |
| 0000 001F FFFF | |
+----------------------------+-------------------------------------+
| 0000 0020 0000 - | 111110xx 10xxxxxx 10xxxxxx 10xxxxxx |
| 0000 03FF FFFF | 10xxxxxx |
+----------------------------+-------------------------------------+
| 0000 0400 0000 - | 1111110x 10xxxxxx 10xxxxxx 10xxxxxx |
| 0000 7FFF FFFF | 10xxxxxx 10xxxxxx |
+----------------------------+-------------------------------------+
| 0000 8000 0000 - | 11111110 10xxxxxx 10xxxxxx 10xxxxxx |
| 000F FFFF FFFF | 10xxxxxx 10xxxxxx 10xxxxxx |
+----------------------------+-------------------------------------+
Table 18If the coded number is a frame number, it MUST be equal to the number of frames preceding the current frame. If the coded number is a sample number, it MUST be equal to the number of samples preceding the current frame. If a stream doesn't meet these requirements, seeking is not (reliably) possible ๐ญ
For example, say a frame belongs to a variable block size stream and has exactly 51 billion samples preceding it. Its coded number gets built like this ๐
Octets 1-5
0b11111110 0b10101111 0b10011111 0b10110101 0b10100011
^^^^^^ ^^^^^^ ^^^^^^ ^^^^^^
| | | Bits 18-13
| | Bits 24-19
| Bits 30-25
Bits 36-31Octets 6-7
0b10111000 0b10000000
^^^^^^ ^^^^^^
| Bits 6-1
Bits 12-7Security moment ๐จ A decoder that relies on the coded number while seeking could be vulnerable to buffer overflows, or could get stuck in an infinite loop, if it seeks in a stream where the coded numbers aren't strictly increasing or are otherwise not valid. See also Section 11.
9.1.6. Uncommon Block Size ๐
If the block size bits from earlier in this section are 0b0110 or 0b0111 (uncommon block size minus 1 stored), the block size minus 1 follows the coded number as either an 8-bit or 16-bit unsigned number, coded big-endian ๐
A value of 65535 (which corresponds to a block size of 65536) is forbidden and MUST NOT be used, because a block size like that can't be represented in the streaminfo metadata block ๐
A value from 0 up to (and including) 14, which corresponds to a block size from 1 to 15, is only valid for the last frame in a stream and MUST NOT be used for any other frame. See also Section 8.2.
9.1.7. Uncommon Sample Rate โจ
If the sample rate bits are 0b1100, 0b1101, or 0b1110 (uncommon sample rate stored), the sample rate follows the uncommon block size (or the coded number if no uncommon block size is stored) as either an 8-bit or a 16-bit unsigned number, coded big-endian.
The sample rate MUST NOT be 0 when the subframe contains audio. A sample rate of 0 MAY be used when non-audio is represented. See Section 8.2 for details ๐ซถ
9.1.8. Frame Header CRC ๐ฅ
Finally, an 8-bit CRC follows the frame/sample number, an uncommon block size, or an uncommon sample rate (depending on whether the latter two are stored). This CRC is initialized with 0 and has the polynomial x^8 + x^2 + x^1 + x^0. This CRC covers the whole frame header before the CRC, including the sync code ๐
9.2. Subframes ๐ฆ
Following the frame header are a number of subframes equal to the number of audio channels. Note that subframes contain a bitstream that doesn't necessarily have to be a whole number of bytes, so only the first subframe starts at a byte boundary ๐ธ
9.2.1. Subframe Header ๐
Each subframe starts with a header. The first bit of the header MUST be 0, followed by 6 bits that describe which subframe type is used, according to the following table, where v is the value of the 6 bits as an unsigned number.
+=====================+===========================================+
| Value | Subframe Type |
+=====================+===========================================+
| 0b000000 | Constant subframe |
+---------------------+-------------------------------------------+
| 0b000001 | Verbatim subframe |
+---------------------+-------------------------------------------+
| 0b000010 - 0b000111 | Reserved |
+---------------------+-------------------------------------------+
| 0b001000 - 0b001100 | Subframe with a fixed predictor of order |
| | v-8; i.e., 0, 1, 2, 3 or 4 |
+---------------------+-------------------------------------------+
| 0b001101 - 0b011111 | Reserved |
+---------------------+-------------------------------------------+
| 0b100000 - 0b111111 | Subframe with a linear predictor of order |
| | v-31; i.e., 1 through 32 (inclusive) |
+---------------------+-------------------------------------------+
Table 19Following the subframe type bits is a bit that flags whether the subframe uses any wasted bits (see Section 9.2.2). If the flag bit is 0, the subframe doesn't use any wasted bits and the subframe header is complete. If the flag bit is 1, the subframe uses wasted bits, and the number of used wasted bits minus 1 appears in unary form, directly following the flag bit ๐ง
9.2.2. Wasted Bits per Sample ๐
Most uncompressed audio file formats can only store audio samples with a bit depth that's an integer number of bytes. Samples where the bit depth isn't an integer number of bytes are usually stored in those formats by padding them with least-significant zero bits, until the bit depth is an integer number of bytes. For example, shifting a 14-bit sample right by 2 pads it to a 16-bit sample, which then has two zero least-significant bits. In this specification, these least-significant zero bits are called wasted bits per sample, or simply wasted bits. They're "wasted" in the sense that they contain no information but get stored anyway ๐
The FLAC format can optionally take advantage of these wasted bits by signaling their presence and coding the subframe without them. To do this, the wasted bits per sample flag in a subframe header is set to 1, and the number of wasted bits per sample (k) minus 1 follows the flag in unary encoding. For example, if k is 3, 0b001 follows. If k = 0, the wasted bits per sample flag is 0 and no unary-coded k follows. In this document, if a subframe header signals a certain number of wasted bits, we say it "uses" these wasted bits ๐
If a subframe uses wasted bits (i.e., k is not equal to 0), samples are coded ignoring k least-significant bits. For example, if a frame that isn't employing stereo decorrelation specifies a sample size of 16 bits per sample in the frame header, and k of a subframe is 3, the samples in that subframe are coded as 13 bits per sample. For more details, see Section 9.2.3 on how the bit depth of a subframe is calculated. A decoder MUST add k least-significant zero bits by shifting left (padding) after decoding a subframe sample. If the frame has left-side, side-right, or mid-side stereo, a decoder MUST perform padding on the subframes before restoring the channels to left and right. The number of wasted bits per sample MUST be such that the resulting number of bits per sample (of which the calculation is explained in Section 9.2.3) is larger than zero ๐ฅ
Besides audio files that have a certain number of wasted bits for the whole file, there are audio files where the number of wasted bits varies. There are DVD-Audio discs in which blocks of samples have had their least-significant bits selectively zeroed, to slightly improve the compression of their otherwise lossless Meridian Lossless Packing codec; see [MLP]. There are also audio processors like lossyWAV (see [lossyWAV]) that zero a number of least-significant bits for a block of samples, which increases the compression in a non-lossless way ๐ Because of this, the number of wasted bits k MAY change between frames and MAY differ between subframes. If the number of wasted bits changes halfway through a subframe (e.g., the first part has 2 wasted bits and the second part has 4 wasted bits), the subframe uses the lowest number of wasted bits. Otherwise, non-zero bits would be discarded, and the process would not be lossless ๐ญ
9.2.3. Constant Subframe ๐ง
In a constant subframe, only a single sample is stored. This sample is stored as an integer number coded big-endian, signed two's complement. The number of bits used to store this sample depends on the bit depth of the current subframe. The bit depth of a subframe is equal to the bit depth as coded in the frame header (see Section 9.1.4), minus the number of used wasted bits coded in the subframe header (see Section 9.2.2). If a subframe is a side subframe (see Section 4.2), the bit depth of that subframe is increased by 1 bit โจ
9.2.4. Verbatim Subframe ๐ง
okay so a verbatim subframe is the simplest vibe ever ๐ it stores every single sample completely unencoded, one after another, in order. no compression, no cap, just raw samples lined up like a fit check ๐ if you want the details on what "unencoded" looks like, peep Section 9.2.3 โจ and the number of samples is given by the block size in the frame header ๐ฆ
9.2.5. Fixed Predictor Subframe ๐
this one is so iconic ๐ญ there are five fixed predictors, one for each prediction order from 0 through 4, all laid out in the table below ๐ the table also has a derivation column that explains why these predictors were chosen. obsessed ngl
+=======+==================================+======================+
| Order | Prediction | Derivation |
+=======+==================================+======================+
| 0 | 0 | N/A |
+-------+----------------------------------+----------------------+
| 1 | a(n-1) | N/A |
+-------+----------------------------------+----------------------+
| 2 | 2 * a(n-1) - a(n-2) | a(n-1) + a'(n-1) |
+-------+----------------------------------+----------------------+
| 3 | 3 * a(n-1) - 3 * a(n-2) + a(n-3) | a(n-1) + a'(n-1) + |
| | | a''(n-1) |
+-------+----------------------------------+----------------------+
| 4 | 4 * a(n-1) - 6 * a(n-2) + 4 * | a(n-1) + a'(n-1) + |
| | a(n-3) - a(n-4) | a''(n-1) + a'''(n-1) |
+-------+----------------------------------+----------------------+
Table 20Where:
nis the number of the sample being predicted.a(n)is the sample being predicted.a(n-1)is the sample before the one being predicted.a'(n-1)is the difference between the previous sample and the sample before that, i.e.,a(n-1) - a(n-2). This is the closest available first-order discrete derivative.a''(n-1)isa'(n-1) - a'(n-2)or the closest available second-order discrete derivative.a'''(n-1)isa''(n-1) - a''(n-2)or the closest available third-order discrete derivative.
okay so a predictor leans on the samples that came before the one it's guessing, which means it can only work once enough samples are known ๐ง since every subframe in FLAC is coded completely independently, the first few samples in each subframe can't be predicted. so a bunch of so-called warm-up samples, equal to the predictor order, get stored instead ๐ซถ these are stored unencoded, skipping the predictor and residual coding stages entirely. see Section 9.2.3 on how samples are stored unencoded. the table below shows how a fixed predictor subframe shows up in the bitstream ๐
+==========+===========================================+
| Data | Description |
+==========+===========================================+
| s(n) | Unencoded warm-up samples (n = subframe's |
| | bits per sample * predictor order). |
+----------+-------------------------------------------+
| Coded | Coded residual as defined in |
| residual | Section 9.2.7 |
+----------+-------------------------------------------+
Table 21because fixed predictors are specified, they don't have to be stored ๐ the fixed predictor order, which lives in the subframe header, tells you which predictor is being used. that's it, that's the whole thing ๐
to encode with a fixed predictor, each sample has its corresponding prediction subtracted and sent off to the residual coder ๐ฆ to decode, you decode the residual first and then add the prediction back for each sample. this makes decoding necessarily sequential within a subframe, since for each sample you need enough fully decoded previous samples to work out the prediction. main character energy, but make it linear ๐
for fixed predictor order 0, the prediction is always 0, so each residual sample is equal to its matching input or decoded sample ๐ the difference between an order 0 fixed predictor and a verbatim subframe is that the verbatim one stores all samples unencoded, while the order 0 predictor runs all its samples through the residual coder. same vibe, different plot twist โจ
the first-order fixed predictor is comparable to how differential pulse-code modulation (DPCM) encoding works, since the residual sample is just the difference between the sample and the one right before it ๐ธ and the higher-order fixed predictors can be understood as polynomials fitted to the previous samples. big math brain moment ๐ง
9.2.6. Linear Predictor Subframe ๐
okay so fixed predictors are great for simple signals, but a (non-fixed) linear predictor on more complex signals can improve compression by making the residual samples even smaller ๐ฅ there's a trade-off though, because storing the predictor coefficients takes up space too. nothing is free bestie ๐
in the FLAC format, a predictor is defined by up to 32 predictor coefficients and a shift. to form a prediction, each coefficient gets multiplied by its matching past sample, the results get summed, and then that sum is shifted ๐ to encode a signal with a linear predictor, each sample has its prediction subtracted and sent to the residual coder. to decode, the residual is decoded and then the prediction is added back for each sample. this means that decoding MUST be a sequential process within a subframe, since enough decoded samples are needed to calculate the prediction for each sample ๐ซถ
the table below shows how a linear predictor subframe looks in the bitstream ๐ฆ
+==========+==========================================+
| Data | Description |
+==========+==========================================+
| s(n) | Unencoded warm-up samples (n = |
| | subframe's bits per sample * LPC order). |
+----------+------------------------------------------+
| u(4) | (Predictor coefficient precision in |
| | bits)-1 (Note: 0b1111 is forbidden). |
+----------+------------------------------------------+
| s(5) | Prediction right shift needed in bits. |
+----------+------------------------------------------+
| s(n) | Predictor coefficients (n = predictor |
| | coefficient precision * LPC order). |
+----------+------------------------------------------+
| Coded | Coded residual as defined in |
| residual | Section 9.2.7. |
+----------+------------------------------------------+
Table 22see Section 9.2.3 on how the warm-up samples are stored unencoded ๐ the predictor coefficients are stored as an integer number coded big-endian, signed two's complement, where the number of bits needed for each coefficient is set by the predictor coefficient precision. the prediction right shift is also signed two's complement, but this number MUST NOT be negative. see Appendix B.4 for an explanation of why ๐ง
please note the order of the predictor coefficients in the bitstream matches which past sample they belong to ๐ in other words, the order is opposite to the chronological order of the samples. so the first predictor coefficient gets multiplied with the sample directly before the one being predicted, the second with the sample before that, and so on. reverse order, full plot twist ๐
9.2.7. Coded Residual ๐
the first two bits in a coded residual tell you which coding method is used ๐ see the table below.
+=============+=============================================+
| Value | Description |
+=============+=============================================+
| 0b00 | Partitioned Rice code with 4-bit parameters |
+-------------+---------------------------------------------+
| 0b01 | Partitioned Rice code with 5-bit parameters |
+-------------+---------------------------------------------+
| 0b10 - 0b11 | Reserved |
+-------------+---------------------------------------------+
Table 23both defined coding methods work the same way but differ in how many bits are used for the Rice parameters ๐ the 4 bits right after the coding method bits form the partition order, which is an unsigned number. the rest of the coded residual is made up of 2^(partition order) partitions. for example, if the 4 bits are 0b1000, the partition order is 8, and the residual is split into 2^8 = 256 partitions. eight partitions? no, two hundred fifty-six. we're not playing ๐ธ
each partition holds a certain number of residual samples ๐ the number in the first partition equals (block size >> partition order) - predictor order. so basically, the block size divided by the number of partitions, minus the predictor order. every other partition holds (block size >> partition order) residual samples. math in the group chat, but it's giving clarity ๐ง
the partition order MUST be such that the block size is evenly divisible by the number of partitions. this means, for example, that only partition order 0 is allowed for all odd block sizes ๐ the partition order also MUST be such that (block size >> partition order) is larger than the predictor order. this means, for example, that with a block size of 4096 and a predictor order of 4, the partition order cannot be larger than 9 ๐ฅ
each partition starts with a parameter ๐ฆ if the coded residual of a subframe uses 4-bit Rice parameters (see Table 23), the first 4 bits of each partition are either a Rice parameter or an escape code. those 4 bits signal an escape code if they're 0b1111, otherwise they hold the Rice parameter as an unsigned number. if the coded residual of the current subframe uses 5-bit Rice parameters, the first 5 bits of each partition signal an escape code if they're 0b11111, and otherwise they hold the Rice parameter as an unsigned number too ๐
9.2.7.1. Escaped Partition ๐
if an escape code was used, the partition doesn't contain a variable-length Rice-coded residual. instead it holds a fixed-length unencoded residual ๐ซถ right after the escape code come 5 bits containing the number of bits each residual sample is stored with, as an unsigned number. the residual samples themselves are stored signed two's complement. for example, when a partition is escaped and each residual sample is stored with 3 bits, the number -1 is represented as 0b111 โจ
it's possible that the number of bits each sample is stored with is 0 ๐ญ that means every residual sample in that partition has a value of 0, and no bits are spent storing the samples. in that case the partition contains nothing except the escape code and 0b00000. zero bits, full vibes ๐
9.2.7.2. Rice Code ๐
okay so if a Rice parameter was given for a partition, that partition holds a Rice-coded residual ๐ The residual samples are signed numbers, but the Rice code wants unsigned ones, so we convert them first. Positive numbers get doubled. Negative numbers get multiplied by -2 and then have 1 subtracted. This trick is called zigzag encoding โจ and the zigzagged result is called the folded residual.
Next, each folded residual sample gets split into two chunks, a most-significant part and a least-significant part ๐ The Rice parameter at the start of each partition decides where that split happens. It's the number of bits in the least-significant part. Then each residual sample is stored by writing the most-significant part in unary, followed by the least-significant part in binary ๐ฆ
Here's an example, bestie ๐ซถ Take a partition with Rice parameter 3 that contains a folded residual sample of 38, which is 0b100110 in binary. The most-significant part is 0b100 (4), so in unary it becomes 0b00001. The least-significant part is 0b110 (6), and that one gets stored as is. So the Rice code word is 0b00001110. All the Rice code words for the residual samples in one partition are stored back to back, one after another ๐ญ
To decode a Rice code word, you count zero bits until you hit a one bit, then read a number of bits equal to the Rice parameter ๐ธ The count of zero bits gets shifted left by the Rice parameter (aka multiplied by 2 to the power of the Rice parameter) and bitwise ORed with (aka added to) the value you just read. That gives you the folded residual value. If the folded residual value is even, you shift it right by 1 bit (aka divide by 2) to get the unfolded residual value. If it's odd, you shift it right by 1 bit and then flip all the bits (aka add 1 and divide by -2) to get the unfolded residual value. This last part assumes negative numbers are signed two's complement on the decoding machine ๐ง
Appendix D walks through decoding a complete coded residual, so go check it out if you want to see it all come together ๐
9.2.7.3. Residual Sample Value Limit ๐ซ
Okay, this one is serious, babe ๐ญ All residual sample values MUST be representable in the range offered by a 32-bit integer, signed one's complement. Equivalently, all residual sample values MUST fall in the range offered by a 32-bit integer signed two's complement, excluding the most negative possible value of that range. That means residual sample values MUST NOT have an absolute value equal to, or larger than, 2 to the power 31. A FLAC encoder MUST make sure of this ๐ If a FLAC encoder can't find a suitable predictor for a certain subframe where all residual samples fit in that range, it MUST default to writing a verbatim subframe. Appendix A explains the cases where residual samples already fit in that range, so you don't need an extra check for those ๐
Why do we even have this limit? It's so decoders can use 32-bit integers when processing residuals, which keeps decoding simple ๐ And the most negative value of a 32-bit two's complement integer is excluded on purpose. The reason is that it can't be negated within a 32-bit signed integer, and most library routines that calculate an absolute value have undefined behavior when they get that value. Nobody wants that chaos, so the value is just left out ๐
9.3. Frame Footer ๐
After the last subframe comes the frame footer โจ If the last subframe isn't byte aligned (aka the number of bits needed to store all the subframes together isn't divisible by 8), zero bits get added until you reach byte alignment. After that comes a 16-bit CRC, initialized with 0, using the polynomial x^16 + x^15 + x^2 + x^0. This CRC covers the whole frame, excluding the 16-bit CRC itself but including the sync code ๐ฆ
10. Container Mappings ๐
FLAC can be used without any container, because it already has the most basic container-type features built in ๐ But that basic container is pretty limited. For more advanced stuff, like combining FLAC audio with video, you need to wrap it in a more capable container ๐ญ Here's the tricky part: because of those container features, FLAC mixes data that belongs to the encoded data (like block size and sample rate) with data that belongs to the container (like checksum and timecode). The choice was made to wrap FLAC frames exactly as they are, which means some data gets duplicated, and it could end up deviating between the FLAC frames and the container around them ๐
Since FLAC frames are completely independent of each other, container features that handle dependencies don't need to be used ๐ง For example, all FLAC frames embedded in Matroska are marked as keyframes when they're stored in a SimpleBlock, and tracks in an MP4 file that only contain FLAC frames don't need a sync sample box. Iconic, right? ๐
10.1. Ogg Mapping ๐ธ
The Ogg container format is defined in [RFC3533] ๐ฆ The first packet of a logical bitstream carrying FLAC data is structured according to the following table.
+=========+=========================================================+
| Data | Description |
+=========+=========================================================+
| 5 | Bytes 0x7F 0x46 0x4C 0x41 0x43 (as also defined by |
| bytes | [RFC5334]). |
+---------+---------------------------------------------------------+
| 2 | Version number of the FLAC-in-Ogg mapping. These bytes |
| bytes | are 0x01 0x00, meaning version 1.0 of the mapping. |
+---------+---------------------------------------------------------+
| 2 | Number of header packets (excluding the first header |
| bytes | packet) as an unsigned number coded big-endian. |
+---------+---------------------------------------------------------+
| 4 | The fLaC signature. |
| bytes | |
+---------+---------------------------------------------------------+
| 4 | A metadata block header for the streaminfo metadata |
| bytes | block. |
+---------+---------------------------------------------------------+
| 34 | A streaminfo metadata block. |
| bytes | |
+---------+---------------------------------------------------------+
Table 24The number of header packets MAY be 0, which means the number of packets that follow is unknown ๐คท This first packet MUST NOT share an Ogg page with any other packets. That means the first page of a logical stream of FLAC-in-Ogg is always 79 bytes โจ
After the first packet come one or more header packets, and each one holds a single metadata block ๐ The first of these packets SHOULD be a Vorbis comment metadata block, for historic reasons ๐ This is different from unencapsulated FLAC streams, where the order of metadata blocks doesn't matter, except for the streaminfo metadata block, and where a Vorbis comment metadata block is optional.
Following the header packets are the audio packets, and each audio packet holds a single FLAC frame ๐ง The first audio packet MUST start on a new Ogg page. In other words, the last metadata block MUST finish its page before any audio packets get encapsulated ๐ซถ
The granule position of all pages containing header packets MUST be 0. For pages containing audio packets, the granule position is the number of the last sample in the last completed packet in the frame. Sample numbering counts interchannel samples too ๐ If a page has no packet end (for example, when it only contains the start of a large packet that continues on the next page), then the granule position is set to the maximum possible value, which is 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF 0xFF.
The granule position of the first audio data page with a completed packet MAY be larger than the number of samples in the packets that complete on that page ๐ Put another way, the apparent sample number of the first sample in the stream, which comes from the granule position and the audio data, MAY be larger than 0. This is useful because, for example, a server can cast a live stream to several clients who joined at different moments, without rewriting the granule position for each client ๐
If an audio stream is encoded where audio properties (sample rate, number of channels, or bit depth) change partway through, this should be handled by finishing the encoding of the current Ogg stream and starting a new Ogg stream, chained onto the previous one ๐ This is called chaining in Ogg. See the Ogg specification [RFC3533] for details ๐
10.2. Matroska Mapping ๐
The Matroska container format is defined in [RFC9559] ๐ฆ The codec ID (EBML path \Segment\Tracks\TrackEntry\CodecID) assigned to signal tracks carrying FLAC data is A_FLAC in ASCII ๐
All FLAC data before the first audio frame (aka the fLaC ASCII signature and all metadata blocks) gets stored as CodecPrivate data (EBML path \Segment\Tracks\TrackEntry\CodecPrivate) ๐ง
Each FLAC frame (including all of its subframes) is treated as a single frame in the context of Matroska โจ
If an audio stream is encoded where audio properties (sample rate, number of channels, or bit depth) change partway through, this should be handled by finishing the current Matroska segment and starting a new one with the new properties ๐ธ
10.3. ISO Base Media File Format (MP4) Mapping ๐
The full encapsulation definition of FLAC audio in MP4 files was considered too extensive to include in this document ๐ You can find a definition document at [FLAC-in-MP4-specification] ๐
11. Security Considerations ๐๐
Okay so, bestie, this section is SERIOUS but also kind of iconic. Like any other codec (such as [RFC6716]), FLAC should not be used with insecure ciphers or cipher modes that are vulnerable to known plaintext attacks. ๐ Some of the header bits, as well as the padding, are easily predictable. Not me going "ugh, that's a lot" ๐ญ
Implementations of the FLAC codec need to take appropriate security considerations into account. Section 2.1 of [RFC4732] provides general information on DoS attacks on end systems and describes some mitigation strategies. ๐ก๏ธ Areas of concern specific to FLAC follow.
It is extremely important for the decoder to be robust against malformed payloads. ๐ Payloads that do not conform to this specification MUST NOT cause the decoder to overrun its allocated memory or take an excessive amount of resources to decode. An overrun in allocated memory could lead to arbitrary code execution by an attacker. The same applies to the encoder, even though problems with encoders are typically rarer. Malformed audio streams MUST NOT cause the encoder to misbehave because this would allow an attacker to attack transcoding gateways.
As with all compression algorithms, both encoding and decoding can produce an output much larger than the input. For decoding, the most extreme possible case of this is a frame with eight constant subframes of block size 65535 and coding for 32-bit PCM. This frame is only 49 bytes in size but codes for more than 2 megabytes of uncompressed PCM data. ๐คฏ For encoding, it is possible to have an even larger size increase, although such behavior is generally considered faulty. This happens if the encoder chooses a Rice parameter that does not fit with the residual that has to be encoded. In such a case, very long unary-coded symbols can appear (in the most extreme case, more than 4 gigabytes per sample). Decoder and encoder implementors are advised to take precautions to prevent excessive resource utilization in such cases.
Where metadata is handled, implementors are advised to either thoroughly test the handling of extreme cases or impose reasonable limits beyond the limits of this specification. For example, a single Vorbis comment metadata block can contain millions of valid fields. It is unlikely such a limit is ever reached except in a potentially malicious file. Likewise, the media type and description of a picture metadata block can be millions of characters long, despite there being no reasonable use of such contents. One possible use case for very long character strings is in lyrics, which can be stored in Vorbis comment metadata block fields. ๐ถ
Various kinds of metadata blocks contain length fields or field counts. While reading a block following these lengths or counts, a decoder MUST make sure higher-level lengths or counts (most importantly, the length field of the metadata block itself) are not exceeded. As some of these length fields code string lengths and memory must be allocated for that, parsers MUST first verify that a block is valid before allocating memory based on its contents, except when explicitly instructed to salvage data from a malformed file. ๐ง
Metadata blocks can also contain references, e.g., the picture metadata block can contain a URI. When following a URI, the security considerations of [RFC3986] apply. Applications MUST obtain explicit user approval to retrieve resources via remote protocols. Following external URIs introduces a tracking risk from on-path observers and the operator of the service hosting the URI. Likewise, the choice of scheme, if it isn't protected like https, could also introduce integrity attacks by an on-path observer. A malicious operator of the service hosting the URI can return arbitrary content that the parser will read. Also, such retrievals can be used in a DDoS attack when the URI points to a potential victim. Therefore, applications need to ask user approval for each retrieval individually, take extra precautions when parsing retrieved data, and cache retrieved resources. Applications MUST obtain explicit user approval to retrieve local resources not located in the same directory as the FLAC file being processed. Since relative URIs are permitted, applications MUST guard against directory traversal attacks and guard against a violation of a same-origin policy if such a policy is being enforced. ๐จ
Seeking in a FLAC stream that is not in a container relies on the coded number in frame headers and optionally a seek table metadata block. Parsers MUST employ thorough checks on whether a found coded number or seek point is at all possible, e.g., whether it is within bounds and not directly contradicting any other coded number or seek point that the seeking process relies on. Without these checks, seeking might get stuck in an infinite loop when numbers in frames are non-consecutive or otherwise not valid, which could be used in DoS attacks. ๐
Implementors are advised to employ fuzz testing combined with different sanitizers on FLAC decoders to find security problems. Ignoring the results of CRC checks improves the efficiency of decoder fuzz testing. ๐งช
See [FLAC-decoder-testbench] for a non-exhaustive list of FLAC files with extreme configurations that lead to crashes or reboots on some known implementations. Besides providing a starting point for security testing, this set of files can also be used to test conformance with this specification. ๐ป
FLAC files may contain executable code, although the FLAC format is not designed for it and it is uncommon. One use case where FLAC is occasionally used to store executable code is when compressing images of mixed-mode CDs, which contain both audio and non-audio data, the non-audio portion of which can contain executable code. In that case, the executable code is stored as if it were audio and is potentially obscured. Of course, it is also possible to store executable code as metadata, for example, as a Vorbis comment with help of a binary-to-text encoding or directly in an application metadata block. Applications MUST NOT execute code contained in FLAC files or present parts of FLAC files as executable code to the user, except when an application has that explicit purpose, e.g., applications reading FLAC files as disc images and presenting it as a virtual disc drive. Absolutely do not run random code from a FLAC file, periodt. ๐ซ๐
12. IANA Considerations ๐ฆ
Okay, so IANA is the org that keeps the official lists. Per this document, IANA has registered one new media type ("audio/flac") and created a new IANA registry, as described in the subsections below. โจ
12.1. Media Type Registration ๐
IANA has registered the "audio/flac" media type as follows. This media type is applicable for FLAC audio that is not packaged in a container as described in Section 10. FLAC audio packaged in such a container will take on the media type of that container, for example, "audio/ogg" when packaged in an Ogg container or "video/mp4" when packaged in an MP4 container alongside a video track. ๐ง
Type name: audio
Subtype name: flac
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: as per RFC 9639
Security considerations: See the security considerations in
Section 11 of RFC 9639.
Interoperability considerations: See the descriptions of past format
changes in Appendix B of RFC 9639.
Published specification: RFC 9639
Applications that use this media type: FFmpeg, Apache, Firefox
Fragment identifier considerations: N/A
Additional information:
Deprecated alias names for this type: audio/x-flac
Magic number(s): fLaC
File extension(s): flac
Macintosh file type code(s): N/A
Uniform Type Identifier: org.xiph.flac conforms to public.audio
Windows Clipboard Format Name: audio/flac
Person & email address to contact for further information: IETF
CELLAR Working Group (cellar@ietf.org)
Intended usage: COMMON
Restrictions on usage: N/A
Author: IETF CELLAR Working Group
Change controller: Internet Engineering Task Force (iesg@ietf.org)12.2. FLAC Application Metadata Block IDs Registry
okay so this is the registry where the FLAC community keeps track of application IDs ๐ โจ IANA made it a brand new registry, and the values line up with the 32-bit identifier from Section 8.4 ๐
if you want to add your own app ID, you need four things: the ID itself, a description, an optional reference to a doc about it, and a Change Controller (either IETF or the registrant's email) ๐ซถ the IDs get handed out on a "First Come First Served" basis [RFC8126], so basically nobody gets blocked from registering an ID the FLAC crowd is already using ๐ฆ this is extra important for audio files that got encoded before anyone registered their ID ๐ญ an application ID can be any 32-bit value, but it's usually 4 human-readable ASCII characters, which is so cute ๐ธ
the starting list in the table below was copied over from the xiph.org registration page (see [ID-registration-page]) ๐ that page isn't maintained anymore because this registry replaced it, so bye bye old page ๐
+===========+==========+===========+===================+==========+
|Application|ASCII |Description|Reference |Change |
|ID |Rendition | | |Controller|
| |(If | | | |
| |Available)| | | |
+===========+==========+===========+===================+==========+
|0x41544348 |ATCH |FlacFile |[FlacFile], RFC |IETF |
| | | |9639 | |
+-----------+----------+-----------+-------------------+----------+
|0x42534F4C |BSOL |beSolo |RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
|0x42554753 |BUGS |Bugs Player|RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
|0x43756573 |Cues |GoldWave |RFC 9639 |IETF |
| | |cue points | | |
+-----------+----------+-----------+-------------------+----------+
|0x46696361 |Fica |CUE |RFC 9639 |IETF |
| | |Splitter | | |
+-----------+----------+-----------+-------------------+----------+
|0x46746F6C |Ftol |flac-tools |RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
|0x4D4F5442 |MOTB |MOTB |RFC 9639 |IETF |
| | |MetaCzar | | |
+-----------+----------+-----------+-------------------+----------+
|0x4D505345 |MPSE |MP3 Stream |RFC 9639 |IETF |
| | |Editor | | |
+-----------+----------+-----------+-------------------+----------+
|0x4D754D4C |MuML |MusicML: |RFC 9639 |IETF |
| | |Music | | |
| | |Metadata | | |
| | |Language | | |
+-----------+----------+-----------+-------------------+----------+
|0x52494646 |RIFF |Sound |RFC 9639 |IETF |
| | |Devices | | |
| | |RIFF chunk | | |
| | |storage | | |
+-----------+----------+-----------+-------------------+----------+
|0x5346464C |SFFL |Sound Font |RFC 9639 |IETF |
| | |FLAC | | |
+-----------+----------+-----------+-------------------+----------+
|0x534F4E59 |SONY |Sony |RFC 9639 |IETF |
| | |Creative | | |
| | |Software | | |
+-----------+----------+-----------+-------------------+----------+
|0x5351455A |SQEZ |flacsqueeze|RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
|0x54745776 |TtWv |TwistedWave|RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
|0x55495453 |UITS |UITS |RFC 9639 |IETF |
| | |Embedding | | |
| | |tools | | |
+-----------+----------+-----------+-------------------+----------+
|0x61696666 |aiff |FLAC AIFF |[Foreign-metadata],|IETF |
| | |chunk |RFC 9639 | |
| | |storage | | |
+-----------+----------+-----------+-------------------+----------+
|0x696D6167 |imag |flac-image |RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
|0x7065656D |peem |Parseable |RFC 9639 |IETF |
| | |Embedded | | |
| | |Extensible | | |
| | |Metadata | | |
+-----------+----------+-----------+-------------------+----------+
|0x71667374 |qfst |QFLAC |RFC 9639 |IETF |
| | |Studio | | |
+-----------+----------+-----------+-------------------+----------+
|0x72696666 |riff |FLAC RIFF |[Foreign-metadata],|IETF |
| | |chunk |RFC 9639 | |
| | |storage | | |
+-----------+----------+-----------+-------------------+----------+
|0x74756E65 |tune |TagTuner |RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
|0x77363420 |w64 |FLAC Wave64|[Foreign-metadata],|IETF |
| | |chunk |RFC 9639 | |
| | |storage | | |
+-----------+----------+-----------+-------------------+----------+
|0x78626174 |xbat |XBAT |RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
|0x786D6364 |xmcd |xmcd |RFC 9639 |IETF |
+-----------+----------+-----------+-------------------+----------+
Table 2513. References
13.1. Normative References
[ISRC-handbook]
International ISRC Registration Authority, "International
Standard Recording Code (ISRC) Handbook", 4th edition,
2021, <https://www.ifpi.org/isrc_handbook/>.
[RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321,
DOI 10.17487/RFC1321, April 1992,
<https://www.rfc-editor.org/info/rfc1321>.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
DOI 10.17487/RFC2046, November 1996,
<https://www.rfc-editor.org/info/rfc2046>.
[RFC2083] Boutell, T., "PNG (Portable Network Graphics)
Specification Version 1.0", RFC 2083,
DOI 10.17487/RFC2083, March 1997,
<https://www.rfc-editor.org/info/rfc2083>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3533] Pfeiffer, S., "The Ogg Encapsulation Format Version 0",
RFC 3533, DOI 10.17487/RFC3533, May 2003,
<https://www.rfc-editor.org/info/rfc3533>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <https://www.rfc-editor.org/info/rfc3629>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC9559] Lhomme, S., Bunkus, M., and D. Rice, "Matroska Media
Container Format Specification", RFC 9559,
DOI 10.17487/RFC9559, October 2024,
<https://www.rfc-editor.org/info/rfc9559>.13.2. Informative References โจ
okay so these are the background reads ๐ Informative means they're here for context, not the spec itself, bestie ๐
- [Durbin] Durbin, J., "The Fitting of Time-Series Models", Revue de l'Institut International de Statistique / Review of the International Statistical Institute, vol. 28, no. 3, pp. 233-44, DOI 10.2307/1401322, 1960,
https://www.jstor.org/stable/1401322. - [FIR] Wikipedia, "Finite impulse response", August 2024,
https://en.wikipedia.org/w/index.php?title=Finite_impulse_response&oldid=1240945295. - [FLAC-decoder-testbench] "The Free Lossless Audio Codec (FLAC) test files", commit aa7b0c6, August 2023,
https://github.com/ietf-wg-cellar/flac-test-files. - [FLAC-implementation] "FLAC",
https://xiph.org/flac/. - [FLAC-in-MP4-specification] "Encapsulation of FLAC in ISO Base Media File Format", commit 78d85dd, July 2022,
https://github.com/xiph/flac/blob/master/doc/isoflac.txt. - [FLAC-specification-github] "The Free Lossless Audio Codec (FLAC) Specification",
https://github.com/ietf-wg-cellar/flac-specification. - [FLAC-wiki-interoperability] "Interoperability considerations", commit 58a06d6,
https://github.com/ietf-wg-cellar/flac-specification/wiki/Interoperability-considerations. - [FlacFile] "FlacFile", Wayback Machine archive, October 2007,
https://web.archive.org/web/20071023070305/http://firestuff.org:80/flacfile/. - [Foreign-metadata] "Specification of foreign metadata storage in FLAC", commit 72787c3, November 2023,
https://github.com/xiph/flac/blob/master/doc/foreign_metadata_storage.md. - [ID-registration-page] Xiph.Org, "ID registry",
https://xiph.org/flac/id.html. - [ID3v2] Nilsson, M., "ID3 tag version 2.4.0 - Native Frames", Wayback Machine archive, November 2000,
https://web.archive.org/web/20220903174949/https://id3.org/id3v2.4.0-frames. - [IEC.60908.1999] International Electrotechnical Commission, "Audio recording - Compact disc digital audio system", IEC 60908:1999-02, 1999,
https://webstore.iec.ch/publication/3885. - [LinearPrediction] Wikipedia, "Linear prediction", August 2023,
https://en.wikipedia.org/w/index.php?title=Linear_prediction&oldid=1169015573. - [Lossless-Compression] Hans, M. and R. W. Schafer, "Lossless compression of digital audio", IEEE Signal Processing Magazine, vol. 18, no. 4, pp. 21-32, DOI 10.1109/79.939834, July 2001,
https://ieeexplore.ieee.org/document/939834. - [lossyWAV] Hydrogenaudio Knowledgebase, "lossyWAV", July 2021,
https://wiki.hydrogenaud.io/index.php?title=LossyWAV&oldid=32877. - [MLP] Gerzon, M. A., Craven, P. G., Stuart, J. R., Law, M. J., and R. J. Wilson, "The MLP Lossless Compression System", Audio Engineering Society Conference: 17th International Conference: High-Quality Audio Codin, September 1999,
https://www.aes.org/e-lib/online/browse.cfm?elib=8082. - [MusicBrainz] MusicBrainz, "Tags & Variables", MusicBrainz Picard v2.10 documentation,
https://picard-docs.musicbrainz.org/en/variables/variables.html. - [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet Denial-of-Service Considerations", RFC 4732, DOI 10.17487/RFC4732, December 2006,
https://www.rfc-editor.org/info/rfc4732. - [RFC5334] Goncalves, I., Pfeiffer, S., and C. Montgomery, "Ogg Media Types", RFC 5334, DOI 10.17487/RFC5334, September 2008,
https://www.rfc-editor.org/info/rfc5334. - [RFC6716] Valin, JM., Vos, K., and T. Terriberry, "Definition of the Opus Audio Codec", RFC 6716, DOI 10.17487/RFC6716, September 2012,
https://www.rfc-editor.org/info/rfc6716. - [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017,
https://www.rfc-editor.org/info/rfc8126. - [Rice] Rice, R. F. and J. R. Plaunt, "Adaptive Variable-Length Coding for Efficient Compression of Spacecraft Television Data", IEEE Transactions on Communication Technology, vol. 19, no. 6, pp. 889-897, DOI 10.1109/TCOM.1971.1090789, December 1971,
https://ieeexplore.ieee.org/document/1090789. - [Robinson-TR156] Robinson, T., "SHORTEN: Simple lossless and near-lossless waveform compression", Cambridge University Engineering Department Technical Report CUED/F-INFENG/TR.156, December 1994,
https://mi.eng.cam.ac.uk/reports/svr-ftp/auto-pdf/robinson_tr156.pdf. - [Shannon] Shannon, C. E., "Communication in the Presence of Noise", Proceedings of the IRE, vol. 37, no. 1, pp. 10-21, DOI 10.1109/JRPROC.1949.232969, January 1949,
https://ieeexplore.ieee.org/document/1697831. - [VarLengthCode] Wikipedia, "Variable-length code", April 2024,
https://en.wikipedia.org/w/index.php?title=Variable-length_code&oldid=1220260423. - [Vorbis] Xiph.Org, "Ogg Vorbis I format specification: comment field and header specification",
https://xiph.org/vorbis/doc/v-comment.html.
Appendix A. Numerical Considerations ๐ข
okay so this appendix is all about keeping things lossless ๐ซถ when you encode and decode sample values, every bit of arithmetic has to be done with integer data types. That way you dodge any sneaky rounding errors that come with floating-point math. Using floats to analyse stuff, like hunting for a good predictor or a Rice parameter, is totally fine, as long as the step where you actually encode the audio samples with that predictor and Rice parameter is done with only integer math โจ
Also, integer overflow can be eliminated by picking data types that are big enough ๐ Using a 64-bit signed data type for all arithmetic on sample values would make sure overflow is impossible, but honestly smaller types are usually chosen for better performance, especially on embedded devices ๐ง This appendix gives guidelines for picking the right data type for each step of encoding and decoding FLAC files.
In this appendix, signed data types are signed two's complement ๐
A.1. Determining the Necessary Data Type Size ๐งฎ
To find the smallest data type size that is guaranteed not to overflow for a given sequence of arithmetic operations, you look at the combination of values that produces the largest possible result ๐
For example, if you add two 16-bit signed integers, the biggest possible result happens when both values are the largest number a 16-bit signed integer can hold. To store that result, you need a signed integer data type with at least 17 bits ๐ Similarly, adding 4 of these values needs 18 bits, adding 8 needs 19 bits, and so on. In general, the number of bits needed when adding numbers together goes up by the log base 2 of the number of values, rounded up to the nearest integer. So if you add 18 unknown values stored in 8-bit signed integers, you need a signed integer data type of at least 13 bits to store the result, because the log base 2 of 18, rounded up, is 5 ๐
When you multiply two numbers, the number of bits needed for the result is the size of the first number plus the size of the second number. For example, if a 16-bit signed integer gets multiplied by another 16-bit signed integer, the result needs at least 32 bits to be stored without overflowing ๐ญ To see this in practice, the largest signed value that fits in 4 bits is -8. (-8)*(-8) is 64, which needs at least 8 bits (signed) to store ๐ฅ
A.2. Stereo Decorrelation ๐ฏโโ๏ธ
When stereo decorrelation is used, the side channel gets one extra bit of bit depth; see Section 4.2 ๐ธ
So while 16-bit signed integers have enough range to store samples from a fully decoded FLAC frame with a bit depth of 16 bits, decoding a side subframe in that kind of file needs a data type with at least 17 bits. That's to store the decoded subframe samples before stereo decorrelation gets undone ๐ฆ
Most FLAC decoders store decoded (subframe) samples as 32-bit values, which is enough for files with bit depths up to (and including) 31 bits. โญ
A.3. Prediction โจ
okay so a prediction is the thing we use to work out the residual when encoding, or add back onto the residual to get the sample value when decoding ๐ . it's formed by multiplying and summing preceding sample values ๐ฆ. to avoid integer overflow, you should consider the combo of preceding sample values and predictor coefficients that gives the biggest possible value ๐ฅ.
to figure out the size of the data type you need to calculate either a residual sample (encoding) or an audio sample value (decoding) in a fixed predictor subframe, you work out the max possible value for these as described in Appendix A.1 and in the table below ๐. for example, if a frame codes for 16-bit audio and has some form of stereo decorrelation, the subframe coding for the side channel would need 16+1+3 bits if a third-order fixed predictor is used ๐.
+=======+==============================+===============+=======+
| Order | Calculation of Residual | Sample Values | Extra |
| | | Summed | Bits |
+=======+==============================+===============+=======+
| 0 | a(n) | 1 | 0 |
+-------+------------------------------+---------------+-------+
| 1 | a(n) - a(n-1) | 2 | 1 |
+-------+------------------------------+---------------+-------+
| 2 | a(n) - 2 * a(n-1) + a(n-2) | 4 | 2 |
+-------+------------------------------+---------------+-------+
| 3 | a(n) - 3 * a(n-1) + 3 * | 8 | 3 |
| | a(n-2) - a(n-3) | | |
+-------+------------------------------+---------------+-------+
| 4 | a(n) - 4 * a(n-1) + 6 * | 16 | 4 |
| | a(n-2) - 4 * a(n-3) + a(n-4) | | |
+-------+------------------------------+---------------+-------+Table 26
where:
nis the number of the sample being predicted ๐งa(n)is the sample being predicted ๐a(n-1)is the sample before the one being predicted,a(n-2)is the sample before that, etc. ๐ธ
for subframes with a linear predictor, the maths gets a little more complicated ๐. each prediction is the sum of several multiplications, and each of those multiplies a sample value with a predictor coefficient. the extra bits needed can be calculated by adding the predictor coefficient precision (in bits) to the bit depth of the audio samples. to account for summing all those multiplications, you add the log base 2 of the predictor order, rounded up ๐.
for example, if the sample bit depth of the source is 24, the current subframe encodes a side channel (see Section 4.2), the predictor order is 12, and the predictor coefficient precision is 15 bits, the minimum required size of the used signed integer data type is at least (24 + 1) + 15 + ceil(log2(12)) = 44 bits ๐ญ. another one: with a side-channel subframe bit depth of 16, a predictor order of 8, and a predictor coefficient precision of 12 bits, the minimum required size of the used signed integer data type is (16 + 1) + 12 + ceil(log2(8)) = 32 bits ๐.
A.4. Residual โจ
as stated in Section 9.2.7, an encoder must make sure residual samples are representable by a 32-bit integer, signed two's complement, excluding the most negative value ๐ฅ. same as in the last section, it's possible to work out when residual samples already implicitly fit and when an extra check is needed ๐ง . this implicit fit happens when residuals would fit a theoretical 31-bit signed integer, because that satisfies both of the criteria mentioned ๐ . when that implicit fit isn't achieved, every residual value has to be calculated and checked one by one ๐.
for the residual of a fixed predictor, the maximum residual sample size was already calculated in the last section ๐ฆ. for a linear predictor, though, the prediction gets shifted right by a certain amount. the number of bits needed for the residual is the number of bits from the last section, reduced by the prediction right shift, and then increased by one bit to account for subtracting the prediction from the current sample on encoding ๐.
take the last example from the previous section, where 32 bits were needed for the prediction. the required data type size for the residual samples with a right shift of 10 bits would be 32 - 10 + 1 = 23 bits, which means it's not necessary to do the aforementioned check ๐.
as another example, when encoding 32-bit PCM with fixed predictors, all predictor orders must be checked ๐. the zero-order fixed predictor is guaranteed to have residual samples that fit a 32-bit signed integer, but it might still produce a residual sample value that is the most negative representable value of that 32-bit signed integer ๐.
note that on decoding, the residual sample values are limited to the range above, but the predictions aren't ๐ซถ. this means decoding the residual samples can happen fully in 32-bit signed integers, but decoders must be sure to do the addition of each residual sample to its matching prediction with a signed integer data type that's wide enough, same as with encoding โจ.
A.5. Rice Coding โจ
when folding (aka zigzag encoding) the residual sample values, you don't need any extra bits if the absolute value of each residual sample is first stored in an unsigned data type of the size from the last step, then doubled, and then has one subtracted depending on whether the residual sample was positive or negative ๐ง. however, lots of implementations choose to require one extra bit of data type size, so zigzag encoding can happen in one step without a cast, instead of the procedure I just described ๐ .
Appendix B. Past Format Changes ๐ฐ๏ธ
this informational appendix documents the changes made to the FLAC format over the years ๐. this info might come in handy when you run into FLAC files made with software that followed the format as it was before the changes in this appendix ๐ซถ.
the FLAC format was first specified in December 2000, and the bitstream format was considered frozen with the release of FLAC 1.0 (the reference encoder/decoder) in July 2001 ๐ง. only changes made since that first stable release are considered in this appendix. changes made to the FLAC streamable subset definition (see Section 7) aren't considered ๐ โโ๏ธ.
B.1. Addition of Blocking Strategy Bit ๐ฆ
this is perhaps the biggest backwards-incompatible change to the specification, published in July 2007 ๐ฑ. before this change, variable block size streams weren't explicitly marked as such by a flag bit in the frame header. a decoder had two ways to detect a variable block size stream: by comparing the minimum and maximum block sizes in the streaminfo metadata block (which are equal for a fixed block size stream), or by detecting a change of block size during a stream if the decoder didn't receive a streaminfo metadata block, which in theory could never happen at all ๐คฏ. since the meaning of the coded number in the frame header depends on whether a stream has a variable block size, this was a problem: the meaning of the coded number couldn't be reliably determined ๐. to fix it, one of the reserved bits was changed to be used as a blocking strategy bit. see also Section 9.1 ๐.
along with the new flag, the meaning of the block size bits (see Section 9.1.1) was subtly changed ๐. at first, block size bit patterns 0b0001-0b0101 and 0b1000-0b1111 could only be used for fixed block size streams, while 0b0110 and 0b0111 could be used for both fixed and variable block size streams. with this change, those restrictions were lifted, and patterns 0b0001-0b1111 are now used for both variable block size and fixed block size streams ๐.
B.2. Restriction of Encoded Residual Samples ๐ธ
another change to the specification was deemed necessary during standardization by the CELLAR Working Group of the IETF ๐ซก. as specified in Section 9.2.7, a limit is imposed on residual samples. that limit wasn't specified before the IETF standardization effort ๐. however, as far as the working group knew, no FLAC encoder at that time produced FLAC files with residual samples going over this limit ๐ . this is mostly because it's very unlikely to hit residual samples over this limit when encoding 24-bit PCM, and encoding PCM with higher bit depths wasn't implemented in any known encoder yet ๐ง. actually, these FLAC encoders would produce corrupt files if they were triggered to produce such residual samples, and it's unlikely any non-experimental encoder would ever do so, even when presented with crafted material ๐. so it wasn't expected that existing implementations would be made non-compliant by this change ๐ซถ.
B.3. Addition of 5-Bit Rice Parameters ๐
one significant addition to the format was the residual coding method using 5-bit Rice parameters โจ. before this addition was published in July 2007, a partitioned Rice code with 4-bit Rice parameters was the only residual coding method specified ๐. the range that coding method offered proved too small when encoding 24-bit PCM, so a second residual coding method was specified. it was identical to the first, but with 5-bit Rice parameters ๐.
B.4. Restriction of LPC Shift to Non-negative Values ๐
as stated in Section 9.2.6, the predictor right shift is a number signed two's complement, which MUST NOT be negative ๐ซ. this is because shifting a number to the right by a negative amount is undefined behavior in the C programming language standard ๐ต. the intended behavior was that a positive number would be a right shift and a negative number would be a left shift ๐คทโโ๏ธ. the FLAC reference encoder was changed in 2007 so it wouldn't generate LPC subframes with a negative predictor right shift ๐. it turned out that using such subframes would only very rarely provide any benefit, and the decoders already widely in use at that point couldn't handle them anyway ๐ .
Appendix C. Interoperability Considerations ๐งฉ
as documented in Appendix B, there have been some changes and additions to the FLAC format ๐. on top of that, implementing certain features of the FLAC format took many years, so early decoder implementations couldn't be tested against files with those features ๐ฐ๏ธ. finally, many lower-quality FLAC decoders only implement just enough features to play back the most common FLAC files ๐ฌ.
this appendix gives some considerations for encoder implementations that are aiming to create highly compatible files ๐ฏ. since this topic might change after this document is published, consult [FLAC-wiki-interoperability] for more up-to-date information ๐.
C.1. Features outside of the Streamable Subset ๐
as described in Section 7, FLAC specifies a subset of its capabilities as the FLAC streamable subset ๐. certain decoders may choose to only decode FLAC files that conform to the limitations of the streamable subset ๐. so maximum compatibility with decoders is achieved when the limitations of the FLAC streamable subset are followed when creating FLAC files ๐ซถ๐ฆ
C.2. Variable Block Size ๐
okay so bestie, here's the tea ๐ซ most encoders are lowkey obsessed with fixed block sizes, because finding the perfect arrangement of variable block sizes for max compression is genuinely hard ๐ญ so the result is that a lot of decoders barely ever get to handle variable block size streams. ๐ that means bugs can hide in there, or some implementations just don't decode them at all ๐ plus, as Appendix B.1 explains, the way variable block size streams are encoded has changed over time โจ so if you want maximum compatibility with decoders, create FLAC files using fixed block size streams. it's giving safe and iconic ๐ ๐ธ
C.3. 5-Bit Rice Parameters ๐ฆ
so the 5-bit Rice parameter coding method (Appendix B.3) showed up quite a few years after FLAC first launched ๐ง which means some early decoders might not be able to decode files that use it ๐ฌ it was specifically made to improve compression of 24-bit PCM audio, and honestly 16-bit PCM audio only rarely benefits from it ๐คทโโ๏ธ so for max compatibility, FLAC files with audio at 16 bits or less should be created without any 5-bit Rice parameters. no cap, keep it simple ๐ซถ
C.4. Rice Escape Code ๐
escaped Rice partitions are seldom used, bestie, because their compression boost turned out to be only very small ๐ฅฒ lots of encoders don't turn them on by default, or can't make them at all, so it's likely that many decoders can't decode them correctly either ๐ soooo for maximum compatibility with decoders, create FLAC files without any escaped Rice partitions. periodt โจ
C.5. Uncommon Block Size ๐
for unknown reasons (and yes, we're all wondering ๐), some decoders only support common block sizes for all but the last block of a stream ๐ so if you want maximum compatibility, create FLAC files using common block sizes, as listed in Section 9.1.1, for all but the last block of a stream. main character energy ๐
C.6. Uncommon Bit Depth ๐
most audio is stored in bit depths that are a whole number of bytes, like 8, 16, or 24 bits ๐ถ but there's audio with other bit depths too, and they're kinda wild. here are a few examples:
- DVD-Audio can store 20-bit PCM audio. ๐ฟ
- DAT and DV can store 12-bit PCM audio. ๐ผ
- NICAM-728 samples at 14 bits, which gets companded to 10 bits. ๐ป
- 8-bit ยต-law can be losslessly converted to 14-bit (Linear) PCM. ๐ฆ
- 8-bit A-law can be losslessly converted to 13-bit (Linear) PCM. ๐ธ
the FLAC format can hold these bit depths directly ๐ but since they're uncommon, some decoders can't process the resulting files correctly ๐ญ the workaround is to store them in a FLAC file with a more common bit depth by padding each sample with zero bits up to a whole number of bytes, and FLAC can efficiently compress those wasted bits without sacrificing compression โจ see Section 9.2.2 for the details.
so, for maximum compatibility with decoders, create FLAC files by padding samples of this audio with zero bits to the bit depth that's the next whole number of bytes. ๐ซถ
heads up, bestie: if the original signal is already padded, you can't reverse this losslessly unless you know the original bit depth ๐จ so to leave no ambiguity, store the original bit depth somewhere, like in a Vorbis comment field or by storing the header of the original file. picking a method is up to the implementor ๐
some decoder implementations only accept FLAC files coding for PCM audio with a bit depth of 16 bits ๐ค and lots of others handle bit depths up to 24 bits, but no higher ๐ for more up-to-date info, check [FLAC-wiki-interoperability] ๐
C.7. Multi-Channel Audio and Uncommon Sample Rates ๐
lowkey, lots of FLAC audio players can't render multi-channel audio or audio at an uncommon sample rate ๐ฉ this isn't really a FLAC-specific problem, but it's worth knowing if you need maximum compatibility with decoders. unlike the other interoperability considerations, this one can't be improved without sacrificing the lossless nature of the FLAC format ๐
from a non-exhaustive inquiry (so not the full picture, babe ๐), a non-negligible number of players, especially hardware players, don't support audio with 3 or more channels or sample rates other than the common ones; see Section 9.1.2 ๐ง
for players that do support multi-channel audio and can render it, many don't parse or use the WAVEFORMATEXTENSIBLE_CHANNEL_MASK tag (see Section 8.6.2) ๐ญ this is also an interoperability consideration, and again, it can't be fixed without sacrificing the lossless nature of FLAC ๐
C.8. Changing Audio Properties Mid-Stream ๐ฆ
each FLAC frame header stores the audio sample rate, bits per sample, and number of channels independently of the streaminfo metadata block and other frame headers ๐ง this was done to permit multicasting of FLAC files, but it also lets these properties change mid-stream ๐ however, many FLAC decoders don't handle those changes, since few other formats can hold such streams, and changing playback properties during playback is often not possible without interrupting it ๐ฌ also, as Section 9 explains, using this feature of FLAC causes various practical problems ๐
even when an audio stream with changing properties is stored in FLAC inside a container that can handle such changes (as recommended in Section 9), many decoders still can't decode it correctly ๐ so, for maximum compatibility with decoders, create FLAC files with a single set of audio properties, where the properties in the streaminfo metadata block (see Section 8.2) and the properties in all frame headers (see Section 9.1) are the same โจ you can get there by splitting an input stream with changing properties at the points where they change, into separate streams or files ๐
Appendix D. Examples ๐
this informational appendix has short examples of FLAC files that get decoded step by step ๐ง it's a more engaging way to understand FLAC than the formal spec ๐ the text assumes you've at least skimmed the specification and that you'll look up terminology there when needed ๐ค the examples mostly focus on the layout of several metadata blocks and subframe types, plus how things like wasted bits and stereo decorrelation affect that layout ๐
the example files were generated by various FLAC encoders ๐ ๏ธ they're shown in hexadecimal or binary, followed by tables and text that point to features by their starting bit positions ๐ฆ each starting position (shortened to "start" in the tables) is a hexadecimal byte position plus a start bit within that byte, separated by a plus sign, and counts start at zero ๐ข for example, a feature starting at the 3rd bit of the 17th byte is referred to as starting at 0x10+2 ๐ง you can find the files explored in these examples at [FLAC-specification-github] ๐
all data in this appendix has been thoroughly verified โ but since the appendix is informational, if anything here conflicts with statements in the formal specification, the formal specification wins ๐
D.1. Decoding Example 1 ๐ธ
this super short example FLAC file codes for PCM audio with two channels, each containing one sample ๐ถ the focus here is on the essential parts of a FLAC file ๐
D.1.1. Example File 1 in Hexadecimal Representation ๐
00000000: 664c 6143 8000 0022 1000 1000 fLaC..."....
0000000c: 0000 0f00 000f 0ac4 42f0 0000 ........B...
00000018: 0001 3e84 b418 07dc 6903 0758 ..>.....i..X
00000024: 6a3d ad1a 2e0f fff8 6918 0000 j=......i...
00000030: bf03 58fd 0312 8baa 9a ..X......D.1.2. Example File 1 in Binary Representation ๐ซง
00000000: 01100110 01001100 01100001 01000011 fLaC
00000004: 10000000 00000000 00000000 00100010 ..."
00000008: 00010000 00000000 00010000 00000000 ....
0000000c: 00000000 00000000 00001111 00000000 ....
00000010: 00000000 00001111 00001010 11000100 ....
00000014: 01000010 11110000 00000000 00000000 B...
00000018: 00000000 00000001 00111110 10000100 ..>.
0000001c: 10110100 00011000 00000111 11011100 ....
00000020: 01101001 00000011 00000111 01011000 i..X
00000024: 01101010 00111101 10101101 00011010 j=..
00000028: 00101110 00001111 11111111 11111000 ....
0000002c: 01101001 00011000 00000000 00000000 i...
00000030: 10111111 00000011 01011000 11111101 ..X.
00000034: 00000011 00010010 10001011 10101010 ....
00000038: 10011010D.1.3. Signature and Streaminfo โจ
okay so the first 4 bytes of the file are the fLaC file signature ๐ right after that comes a metadata block. the signature and the first metadata block header are broken down in this table ๐
+========+=========+============+===========================+
| Start | Length | Contents | Description |
+========+=========+============+===========================+
| 0x00+0 | 4 bytes | 0x664C6143 | fLaC |
+--------+---------+------------+---------------------------+
| 0x04+0 | 1 bit | 0b1 | Last metadata block |
+--------+---------+------------+---------------------------+
| 0x04+1 | 7 bits | 0b0000000 | Streaminfo metadata block |
+--------+---------+------------+---------------------------+
| 0x05+0 | 3 bytes | 0x000022 | Length of 34 bytes |
+--------+---------+------------+---------------------------+Table 27
bestie, the header says this is the last metadata block ๐ so the first audio frame starts right after it. you get its position by taking the first byte after the metadata block header and adding the block length, which is 8+34 = 42 or 0x2a ๐ง and guess what, 0x2a really does hold the frame sync code for fixed block size streams, which is 0xfff8 ๐ญ iconic!!
the streaminfo metadata block contents are broken down in this table ๐
+========+==========+====================+==========================+
| Start | Length | Contents | Description |
+========+==========+====================+==========================+
| 0x08+0 | 2 bytes | 0x1000 | Min. block size 4096 |
+--------+----------+--------------------+--------------------------+
| 0x0a+0 | 2 bytes | 0x1000 | Max. block size 4096 |
+--------+----------+--------------------+--------------------------+
| 0x0c+0 | 3 bytes | 0x00000f | Min. frame size 15 bytes |
+--------+----------+--------------------+--------------------------+
| 0x0f+0 | 3 bytes | 0x00000f | Max. frame size 15 bytes |
+--------+----------+--------------------+--------------------------+
| 0x12+0 | 20 bits | 0x0ac4, 0b0100 | Sample rate 44100 hertz |
+--------+----------+--------------------+--------------------------+
| 0x14+4 | 3 bits | 0b001 | 2 channels |
+--------+----------+--------------------+--------------------------+
| 0x14+7 | 5 bits | 0b01111 | Sample bit depth 16 |
+--------+----------+--------------------+--------------------------+
| 0x15+4 | 36 bits | 0b0000, 0x00000001 | Total no. of samples 1 |
+--------+----------+--------------------+--------------------------+
| 0x1a | 16 | (...) | MD5 checksum |
| | bytes | | |
+--------+----------+--------------------+--------------------------+Table 28
the min and max block sizes are both 4096 ๐ธ the encoder apparently planned to use that block size, but only 1 interchannel sample was provided, so no frames with 4096 samples actually show up in this file ๐
quick reminder: anywhere a number of samples gets mentioned (block size, total number of samples, sample rate), we mean interchannel samples ๐ซถ
the MD5 checksum (starting at 0x1a) is 0x3e84 b418 07dc 6903 0758 6a3d ad1a 2e0f ๐ it gets validated after the samples are decoded, so hold that thought ๐
D.1.4. Audio Frames ๐ง
the frame header starts at position 0x2a and is broken down in this table ๐ฆ
+========+=========+=================+===================+
| Start | Length | Contents | Description |
+========+=========+=================+===================+
| 0x2a+0 | 15 bits | 0xff, 0b1111100 | Frame sync |
+--------+---------+-----------------+-------------------+
| 0x2b+7 | 1 bit | 0b0 | Blocking strategy |
+--------+---------+-----------------+-------------------+
| 0x2c+0 | 4 bits | 0b0110 | 8-bit block size |
| | | | further down |
+--------+---------+-----------------+-------------------+
| 0x2c+4 | 4 bits | 0b1001 | Sample rate 44.1 |
| | | | kHz |
+--------+---------+-----------------+-------------------+
| 0x2d+0 | 4 bits | 0b0001 | Stereo, no |
| | | | decorrelation |
+--------+---------+-----------------+-------------------+
| 0x2d+4 | 3 bits | 0b100 | Bit depth 16 bits |
+--------+---------+-----------------+-------------------+
| 0x2d+7 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+-----------------+-------------------+
| 0x2e+0 | 1 byte | 0x00 | Frame number 0 |
+--------+---------+-----------------+-------------------+
| 0x2f+0 | 1 byte | 0x00 | Block size 1 |
+--------+---------+-----------------+-------------------+
| 0x30+0 | 1 byte | 0xbf | Frame header CRC |
+--------+---------+-----------------+-------------------+Table 29
since this is a fixed block size stream, the number at 0x2e is a frame number ๐ and because it's smaller than 128, it only takes 1 byte to encode ๐
at byte 0x31, the first subframe starts ๐ it's broken down in this table ๐
+========+=========+================+=========================+
| Start | Length | Contents | Description |
+========+=========+================+=========================+
| 0x31+0 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+----------------+-------------------------+
| 0x31+1 | 6 bits | 0b000001 | Verbatim subframe |
+--------+---------+----------------+-------------------------+
| 0x31+7 | 1 bit | 0b1 | Wasted bits used |
+--------+---------+----------------+-------------------------+
| 0x32+0 | 2 bits | 0b01 | 2 wasted bits used |
+--------+---------+----------------+-------------------------+
| 0x32+2 | 14 bits | 0b011000, 0xfd | 14-bit unencoded sample |
+--------+---------+----------------+-------------------------+Table 30
the wasted bits flag is 1 in this subframe, so a unary-coded number comes next ๐ง starting at 0x32 we see 0b01, which unary codes for 1, meaning this subframe uses 2 wasted bits โจ
since it's a verbatim subframe, it only holds unencoded sample values ๐ with a block size of 1, that's just one sample. the audio is 16 bits deep, but the subframe header says 2 wasted bits are in use, so only 14 bits get stored ๐ธ there's no stereo decorrelation here, so a bit depth increase for the side channel doesn't apply ngl. the next 14 bits (starting at position 0x32+2) hold the unencoded sample, big-endian and signed two's complement ๐ซถ they read 0b011000 11111101, or 6397. that value gets shifted left by 2 bits to account for the wasted bits, so it becomes 0b011000 11111101 00, or 25588 ๐ฅ
the second subframe starts at 0x34 and is broken down in this table ๐ฆ
+========+=========+==============+=========================+
| Start | Length | Contents | Description |
+========+=========+==============+=========================+
| 0x34+0 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+--------------+-------------------------+
| 0x34+1 | 6 bits | 0b000001 | Verbatim subframe |
+--------+---------+--------------+-------------------------+
| 0x34+7 | 1 bit | 0b1 | Wasted bits used |
+--------+---------+--------------+-------------------------+
| 0x35+0 | 4 bits | 0b0001 | 4 wasted bits used |
+--------+---------+--------------+-------------------------+
| 0x35+4 | 12 bits | 0b0010, 0x8b | 12-bit unencoded sample |
+--------+---------+--------------+-------------------------+Table 31
the wasted bits flag is also one, but this time the unary-coded number that follows is 4 bits long, so 4 wasted bits are in use ๐ that means the sample is stored in 12 bits. the sample value is 0b0010 10001011, or 651. this one has to be shifted left by 4 bits, so it becomes 0b0010 10001011 0000, or 10416 ๐
at this point we would undo stereo decorrelation, if that applied ๐
the last subframe ends byte-aligned, so no padding bits follow it ๐ the next 2 bytes, starting at 0x38, hold the frame CRC. since this is the only frame in the file, the file ends right after the CRC ๐ง
to validate the MD5 checksum, we line up the samples interleaved, byte-aligned, little-endian, signed two's complement ๐ the first sample, 25588, translates to 0xf463, and the second sample, 10416, translates to 0xb028. when you compute the MD5 checksum with 0xf463b028 as input, you get the checksum from the header, so the decoding was lossless ๐ญ๐
D.2. Decoding Example 2 ๐ธ
this FLAC file is bigger than the first example, but it still only has a tiny bit of audio ๐ฆ the focus here is decoding a subframe with a fixed predictor and a coded residual. it also has a very short seek table, a Vorbis comment metadata block, and a padding metadata block, so there's a lot going on for something this small ๐
D.2.1. Example File 2 in Hexadecimal Representation ๐ง
00000000: 664c 6143 0000 0022 0010 0010 fLaC..."....
0000000c: 0000 1700 0044 0ac4 42f0 0000 .....D..B...
00000018: 0013 d5b0 5649 75e9 8b8d 8b93 ....VIu.....
00000024: 0422 757b 8103 0300 0012 0000 ."u{........
00000030: 0000 0000 0000 0000 0000 0000 ............
0000003c: 0000 0010 0400 003a 2000 0000 .......: ...
00000048: 7265 6665 7265 6e63 6520 6c69 reference li
00000054: 6246 4c41 4320 312e 332e 3320 bFLAC 1.3.3
00000060: 3230 3139 3038 3034 0100 0000 20190804....
0000006c: 0e00 0000 5449 544c 453d d7a9 ....TITLE=..
00000078: d79c d795 d79d 8100 0006 0000 ............
00000084: 0000 0000 fff8 6998 000f 9912 ......i.....
00000090: 0867 0162 3d14 4299 8f5d f70d .g.b=.B..]..
0000009c: 6fe0 0c17 caeb 2100 0ee7 a77a o.....!....z
000000a8: 24a1 590c 1217 b603 097b 784f $.Y......{xO
000000b4: aa9a 33d2 85e0 70ad 5b1b 4851 ..3...p.[.HQ
000000c0: b401 0d99 d2cd 1a68 f1e6 b810 .......h....
000000cc: fff8 6918 0102 a402 c382 c40b ..i.........
000000d8: c14a 03ee 48dd 03b6 7c13 30 .J..H...|.0D.2.2. Example File 2 in Binary Representation (Only Audio Frames) ๐
okay bestie, here are the same audio-frame bytes written out bit by bit ๐คโจ it's giving very clean binary energy
00000088: 11111111 11111000 01101001 10011000 ..i.
0000008c: 00000000 00001111 10011001 00010010 ....
00000090: 00001000 01100111 00000001 01100010 .g.b
00000094: 00111101 00010100 01000010 10011001 =.B.
00000098: 10001111 01011101 11110111 00001101 .]..
0000009c: 01101111 11100000 00001100 00010111 o...
000000a0: 11001010 11101011 00100001 00000000 ..!.
000000a4: 00001110 11100111 10100111 01111010 ...z
000000a8: 00100100 10100001 01011001 00001100 $.Y.
000000ac: 00010010 00010111 10110110 00000011 ....
000000b0: 00001001 01111011 01111000 01001111 .{xO
000000b4: 10101010 10011010 00110011 11010010 ..3.
000000b8: 10000101 11100000 01110000 10101101 ..p.
000000bc: 01011011 00011011 01001000 01010001 [.HQ
000000c0: 10110100 00000001 00001101 10011001 ....
000000c4: 11010010 11001101 00011010 01101000 ...h
000000c8: 11110001 11100110 10111000 00010000 ....
000000cc: 11111111 11111000 01101001 00011000 ..i.
000000d0: 00000001 00000010 10100100 00000010 ....
000000d4: 11000011 10000010 11000100 00001011 ....
000000d8: 11000001 01001010 00000011 11101110 .J..
000000dc: 01001000 11011101 00000011 10110110 H...
000000e0: 01111100 00010011 00110000 |.0D.2.3. Streaminfo Metadata Block ๐
the streaminfo block (header included) is basically the same as in example 1, so we only need to look at the parts that changed ๐ here's the table of differences:
+========+=========+============+=============================+
| Start | Length | Contents | Description |
+========+=========+============+=============================+
| 0x04+0 | 1 bit | 0b0 | Not the last metadata block |
+--------+---------+------------+-----------------------------+
| 0x08+0 | 2 bytes | 0x0010 | Min. block size 16 |
+--------+---------+------------+-----------------------------+
| 0x0a+0 | 2 bytes | 0x0010 | Max. block size 16 |
+--------+---------+------------+-----------------------------+
| 0x0c+0 | 3 bytes | 0x000017 | Min. frame size 23 bytes |
+--------+---------+------------+-----------------------------+
| 0x0f+0 | 3 bytes | 0x000044 | Max. frame size 68 bytes |
+--------+---------+------------+-----------------------------+
| 0x15+4 | 36 bits | 0b0000, | Total no. of samples 19 |
| | | 0x00000013 | |
+--------+---------+------------+-----------------------------+
| 0x1a | 16 | (...) | MD5 checksum |
| | bytes | | |
+--------+---------+------------+-----------------------------+
Table 32this time the min and max block sizes actually show up in the file ๐ there's one block of 16 samples, and the last block (3 samples) doesn't count toward the minimum block size, iconic behaviour ๐
the MD5 checksum is 0xd5b0 5649 75e9 8b8d 8b93 0422 757b 8103, and we'll check it at the very end of this example ๐ง
D.2.4. Seek Table ๐
the seek table only has one entry ๐ฅบ it isn't really useful here since it just points at the first frame, but honestly it's enough for this example. here's the breakdown:
+========+========+====================+================+
| Start | Length | Contents | Description |
+========+========+====================+================+
| 0x2a+0 | 1 bit | 0b0 | Not the last |
| | | | metadata block |
+--------+--------+--------------------+----------------+
| 0x2a+1 | 7 bits | 0b0000011 | Seek table |
| | | | metadata block |
+--------+--------+--------------------+----------------+
| 0x2b+0 | 3 | 0x000012 | Length 18 |
| | bytes | | bytes |
+--------+--------+--------------------+----------------+
| 0x2e+0 | 8 | 0x0000000000000000 | Seek point to |
| | bytes | | sample 0 |
+--------+--------+--------------------+----------------+
| 0x36+0 | 8 | 0x0000000000000000 | Seek point to |
| | bytes | | offset 0 |
+--------+--------+--------------------+----------------+
| 0x3e+0 | 2 | 0x0010 | Seek point to |
| | bytes | | block size 16 |
+--------+--------+--------------------+----------------+
Table 33D.2.5. Vorbis Comment ๐
the Vorbis comment block holds the vendor string plus a single comment ๐ฌ breakdown:
+========+==========+============+===============================+
| Start | Length | Contents | Description |
+========+==========+============+===============================+
| 0x40+0 | 1 bit | 0b0 | Not the last metadata block |
+--------+----------+------------+-------------------------------+
| 0x40+1 | 7 bits | 0b0000100 | Vorbis comment metadata block |
+--------+----------+------------+-------------------------------+
| 0x41+0 | 3 bytes | 0x00003a | Length 58 bytes |
+--------+----------+------------+-------------------------------+
| 0x44+0 | 4 bytes | 0x20000000 | Vendor string length 32 bytes |
+--------+----------+------------+-------------------------------+
| 0x48+0 | 32 bytes | (...) | Vendor string |
+--------+----------+------------+-------------------------------+
| 0x68+0 | 4 bytes | 0x01000000 | Number of fields 1 |
+--------+----------+------------+-------------------------------+
| 0x6c+0 | 4 bytes | 0x0e000000 | Field length 14 bytes |
+--------+----------+------------+-------------------------------+
| 0x70+0 | 14 bytes | (...) | Field contents |
+--------+----------+------------+-------------------------------+
Table 34the vendor string is reference libFLAC 1.3.3 20190804 ๐ถ and the only field's contents are
TITLE=ืฉืืื
reading it left to right, the characters in the field content are: "ืฉ" (HEBREW LETTER SHIN, U+05E9), "ื" (HEBREW LETTER LAMED, U+05DC), "ื" (HEBREW LETTER VAV, U+05D5), "ื" (HEBREW LETTER FINAL MEM, U+05DD).
the Vorbis comment field is 14 bytes but only 10 characters, because four of those characters take 2 bytes each ๐คฏ bytes and characters are not the same thing, bestie!
D.2.6. Padding ๐ซถ
the last metadata block is a very short padding block ๐ธ
+========+=========+================+========================+
| Start | Length | Contents | Description |
+========+=========+================+========================+
| 0x7e+0 | 1 bit | 0b1 | Last metadata block |
+--------+---------+----------------+------------------------+
| 0x7e+1 | 7 bits | 0b0000001 | Padding metadata block |
+--------+---------+----------------+------------------------+
| 0x7f+0 | 3 bytes | 0x000006 | Length 6 byte |
+--------+---------+----------------+------------------------+
| 0x82+0 | 6 bytes | 0x000000000000 | Padding bytes |
+--------+---------+----------------+------------------------+
Table 35D.2.7. First Audio Frame ๐ฆ
the frame header starts at position 0x88 ๐ here's its breakdown:
+========+=========+=================+===================+
| Start | Length | Contents | Description |
+========+=========+=================+===================+
| 0x88+0 | 15 bits | 0xff, 0b1111100 | Frame sync |
+--------+---------+-----------------+-------------------+
| 0x89+7 | 1 bit | 0b0 | Blocking strategy |
+--------+---------+-----------------+-------------------+
| 0x8a+0 | 4 bits | 0b0110 | 8-bit block size |
| | | | further down |
+--------+---------+-----------------+-------------------+
| 0x8a+4 | 4 bits | 0b1001 | Sample rate 44.1 |
| | | | kHz |
+--------+---------+-----------------+-------------------+
| 0x8b+0 | 4 bits | 0b1001 | Side-right stereo |
+--------+---------+-----------------+-------------------+
| 0x8b+4 | 3 bits | 0b100 | Bit depth 16 bit |
+--------+---------+-----------------+-------------------+
| 0x8b+7 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+-----------------+-------------------+
| 0x8c+0 | 1 byte | 0x00 | Frame number 0 |
+--------+---------+-----------------+-------------------+
| 0x8d+0 | 1 byte | 0x0f | Block size 16 |
+--------+---------+-----------------+-------------------+
| 0x8e+0 | 1 byte | 0x99 | Frame header CRC |
+--------+---------+-----------------+-------------------+
Table 36the first subframe starts at byte 0x8f ๐ง this subframe codes a side channel, so the bit depth goes up by 1 bit, from 16 to 17 bits ๐ฅ you can really see that in the unencoded warm-up sample. here's the breakdown, leaving out the coded residual:
+========+=========+=============+===========================+
| Start | Length | Contents | Description |
+========+=========+=============+===========================+
| 0x8f+0 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+-------------+---------------------------+
| 0x8f+1 | 6 bits | 0b001001 | Fixed subframe, 1st order |
+--------+---------+-------------+---------------------------+
| 0x8f+7 | 1 bit | 0b0 | No wasted bits used |
+--------+---------+-------------+---------------------------+
| 0x90+0 | 17 bits | 0x0867, 0b0 | Unencoded warm-up sample |
+--------+---------+-------------+---------------------------+
Table 37the coded residual is next ๐ all quotients are unary coded, and all remainders are stored unencoded, with the number of bits set by the Rice parameter.
At this point, the decoder should know it's done with the coded residual ๐ , since it got 16 samples total: 1 warm-up sample and 15 residual samples ๐. Each residual sample comes from the quotient and remainder, plus undoing the zigzag encoding ๐ง. For example, the first zigzag-encoded residual is 3 * 2^11 + 244 = 6388 โจ. That's even, so we undo the zigzag by dividing by 2, and the residual sample value is 3194 ๐ซถ. Here's the full table of that for every residual sample ๐
+=====+=======+=================+=====================+
| 0x92+1 ...Wait, let me put the exact tables in properly ๐
+========+========+=================+=================+
| Start | Length | Contents | Description |
+========+========+=================+=================+
| 0x92+1 | 2 bits | 0b00 | Rice code with |
| | | | 4-bit parameter |
+--------+--------+-----------------+-----------------+
| 0x92+3 | 4 bits | 0b0000 | Partition order |
| | | | 0 |
+--------+--------+-----------------+-----------------+
| 0x92+7 | 4 bits | 0b1011 | Rice parameter |
| | | | 11 |
+--------+--------+-----------------+-----------------+
| 0x93+3 | 4 bits | 0b0001 | Quotient 3 |
+--------+--------+-----------------+-----------------+
| 0x93+7 | 11 | 0b00011110100 | Remainder 244 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0x95+2 | 2 bits | 0b01 | Quotient 1 |
+--------+--------+-----------------+-----------------+
| 0x95+4 | 11 | 0b01000100001 | Remainder 545 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0x96+7 | 2 bits | 0b01 | Quotient 1 |
+--------+--------+-----------------+-----------------+
| 0x97+1 | 11 | 0b00110011000 | Remainder 408 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0x98+4 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0x98+5 | 11 | 0b11101011101 | Remainder 1885 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0x9a+0 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0x9a+1 | 11 | 0b11101110000 | Remainder 1904 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0x9b+4 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0x9b+5 | 11 | 0b10101101111 | Remainder 1391 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0x9d+0 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0x9d+1 | 11 | 0b11000000000 | Remainder 1536 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0x9e+4 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0x9e+5 | 11 | 0b10000010111 | Remainder 1047 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0xa0+0 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0xa0+1 | 11 | 0b10010101110 | Remainder 1198 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0xa1+4 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0xa1+5 | 11 | 0b01100100001 | Remainder 801 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0xa3+0 | 13 | 0b0000000000001 | Quotient 12 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0xa4+5 | 11 | 0b11011100111 | Remainder 1767 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0xa6+0 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0xa6+1 | 11 | 0b01001110111 | Remainder 631 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0xa7+4 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0xa7+5 | 11 | 0b01000100100 | Remainder 548 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0xa9+0 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0xa9+1 | 11 | 0b01000010101 | Remainder 533 |
| | bits | | |
+--------+--------+-----------------+-----------------+
| 0xaa+4 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+-----------------+-----------------+
| 0xaa+5 | 11 | 0b00100001100 | Remainder 268 |
| | bits | | |
+--------+--------+-----------------+-----------------+
Table 38 +============+============+========+=======+
| Subframe 1 | Subframe 2 | Left | Right |
+============+============+========+=======+
| 4302 | 6070 | 10372 | 6070 |
+------------+------------+--------+-------+
| 7496 | 10545 | 18041 | 10545 |
+------------+------------+--------+-------+
| 6199 | 8743 | 14942 | 8743 |
+------------+------------+--------+-------+
| 7427 | 10449 | 17876 | 10449 |
+------------+------------+--------+-------+
| 6484 | 9143 | 15627 | 9143 |
+------------+------------+--------+-------+
| 7436 | 10463 | 17899 | 10463 |
+------------+------------+--------+-------+
| 6740 | 9502 | 16242 | 9502 |
+------------+------------+--------+-------+
| 7508 | 10569 | 18077 | 10569 |
+------------+------------+--------+-------+
| 6984 | 9840 | 16824 | 9840 |
+------------+------------+--------+-------+
| 7583 | 10680 | 18263 | 10680 |
+------------+------------+--------+-------+
| 7182 | 10113 | 17295 | 10113 |
+------------+------------+--------+-------+
| -5990 | -8428 | -14418 | -8428 |
+------------+------------+--------+-------+
| -6306 | -8895 | -15201 | -8895 |
+------------+------------+--------+-------+
| -6032 | -8476 | -14508 | -8476 |
+------------+------------+--------+-------+
| -6299 | -8896 | -15195 | -8896 |
+------------+------------+--------+-------+
| -6165 | -8653 | -14818 | -8653 |
+------------+------------+--------+-------+
Table 41Since the second subframe ends byte-aligned, there are no padding bits after it, and then the last 2 bytes of the frame hold the frame CRC. That's the whole first frame wrapped up ๐
D.2.8. Second Audio Frame โจ
The second audio frame is basically the first one's twin ๐ฏโโ๏ธ, except this time there are 3 samples (not 1!) hanging out in it. Same energy, bigger guest list ๐
The frame header kicks off at position 0xcc, and here's the breakdown ๐
+========+=========+=================+===================+
| Start | Length | Contents | Description |
+========+=========+=================+===================+
| 0xcc+0 | 15 bits | 0xff, 0b1111100 | Frame sync |
+--------+---------+-----------------+-------------------+
| 0xcd+7 | 1 bit | 0b0 | Blocking strategy |
+--------+---------+-----------------+-------------------+
| 0xce+0 | 4 bits | 0b0110 | 8-bit block size |
| | | | further down |
+--------+---------+-----------------+-------------------+
| 0xce+4 | 4 bits | 0b1001 | Sample rate 44.1 |
| | | | kHz |
+--------+---------+-----------------+-------------------+
| 0xcf+0 | 4 bits | 0b0001 | Stereo, no |
| | | | decorrelation |
+--------+---------+-----------------+-------------------+
| 0xcf+4 | 3 bits | 0b100 | Bit depth 16 bits |
+--------+---------+-----------------+-------------------+
| 0xcf+7 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+-----------------+-------------------+
| 0xd0+0 | 1 byte | 0x01 | Frame number 1 |
+--------+---------+-----------------+-------------------+
| 0xd1+0 | 1 byte | 0x02 | Block size 3 |
+--------+---------+-----------------+-------------------+
| 0xd2+0 | 1 byte | 0xa4 | Frame header CRC |
+--------+---------+-----------------+-------------------+
Table 42The first subframe starts at 0xd3+0, and its breakdown is right here ๐ฆ
+========+=========+==========+=========================+
| Start | Length | Contents | Description |
+========+=========+==========+=========================+
| 0xd3+0 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+----------+-------------------------+
| 0xd3+1 | 6 bits | 0b000001 | Verbatim subframe |
+--------+---------+----------+-------------------------+
| 0xd3+7 | 1 bit | 0b0 | No wasted bits used |
+--------+---------+----------+-------------------------+
| 0xd4+0 | 16 bits | 0xc382 | 16-bit unencoded sample |
+--------+---------+----------+-------------------------+
| 0xd6+0 | 16 bits | 0xc40b | 16-bit unencoded sample |
+--------+---------+----------+-------------------------+
| 0xd8+0 | 16 bits | 0xc14a | 16-bit unencoded sample |
+--------+---------+----------+-------------------------+
Table 43The second subframe starts at 0xda+0, and it's laid out in this table ๐ธ
+========+=========+===================+=========================+
| Start | Length | Contents | Description |
+========+=========+===================+=========================+
| 0xda+0 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+-------------------+-------------------------+
| 0xda+1 | 6 bits | 0b000001 | Verbatim subframe |
+--------+---------+-------------------+-------------------------+
| 0xda+7 | 1 bit | 0b1 | Wasted bits used |
+--------+---------+-------------------+-------------------------+
| 0xdb+0 | 1 bit | 0b1 | 1 wasted bit used |
+--------+---------+-------------------+-------------------------+
| 0xdb+1 | 15 bits | 0b110111001001000 | 15-bit unencoded sample |
+--------+---------+-------------------+-------------------------+
| 0xdd+0 | 15 bits | 0b110111010000001 | 15-bit unencoded sample |
+--------+---------+-------------------+-------------------------+
| 0xde+7 | 15 bits | 0b110110110011111 | 15-bit unencoded sample |
+--------+---------+-------------------+-------------------------+
Table 44Because this subframe uses wasted bits, those 15-bit unencoded samples need to be shifted left by 1 bit ๐ซถ For example, sample 1 is stored as -4536 and becomes -9072 after shifting left 1 bit.
Last but not least, the last subframe doesn't end on byte alignment, so 2 padding bits get added before the 2-byte frame CRC, which follows at 0xe1+0 ๐
D.2.9. MD5 Checksum Verification ๐ฅ
All samples in the file have been decoded, so we can finally verify the MD5 checksum! All sample values must be interleaved and stored signed coded little-endian. The result comes in groups of 12 samples (i.e., 6 interchannel samples) per line, and it looks like this ๐
0x8428 B617 7946 3129 5E3A 2722 D445 D128 0B3D B723 EB45 DF28
0x723f 1E25 9D46 4929 B841 7026 5747 B829 8F43 8127 AEC7 14DF
0x9FC4 41DD 54C7 E4DE A5C4 40DD 1EC6 33DE 82C3 90DC 0BC4 02DD
0x4AC1 3EDBThe MD5 checksum of this is indeed the same as the one found in the streaminfo metadata block. Checksum match, bestie ๐โจ
D.3. Decoding Example 3 ๐ง
This example is once again a very short FLAC file. The focus here is on decoding a subframe with a linear predictor and a coded residual with more than one partition. Ngl, this is the spicy one ๐ถ๏ธ๐
D.3.1. Example File 3 in Hexadecimal Representation ๐
00000000: 664c 6143 8000 0022 1000 1000 fLaC..."....
0000000c: 0000 1f00 001f 07d0 0070 0000 .........p..
00000018: 0018 f8f9 e396 f5cb cfc6 dc80 ............
00000024: 7f99 7790 6b32 fff8 6802 0017 ..w.k2..h...
00000030: e944 004f 6f31 3d10 47d2 27cb .D.Oo1=.G.'.
0000003c: 6d09 0831 452b dc28 2222 8057 m..1E+.("".W
00000048: a3 .D.3.2. Example File 3 in Binary Representation (Only Audio Frame) ๐ฆ
0000002a: 11111111 11111000 01101000 00000010 ..h.
0000002e: 00000000 00010111 11101001 01000100 ...D
00000032: 00000000 01001111 01101111 00110001 .Oo1
00000036: 00111101 00010000 01000111 11010010 =.G.
0000003a: 00100111 11001011 01101101 00001001 '.m.
0000003e: 00001000 00110001 01000101 00101011 .1E+
00000042: 11011100 00101000 00100010 00100010 .(""
00000046: 10000000 01010111 10100011 .W.D.3.3. Streaminfo Metadata Block ๐
Most of the streaminfo metadata block, including its header, is the same as in example 1, so only the parts that are different are listed in the following table. Less reading, more vibes โจ
+========+==========+====================+==========================+
| Start | Length | Contents | Description |
+========+==========+====================+==========================+
| 0x0c+0 | 3 bytes | 0x00001f | Min. frame size 31 bytes |
+--------+----------+--------------------+--------------------------+
| 0x0f+0 | 3 bytes | 0x00001f | Max. frame size 31 bytes |
+--------+----------+--------------------+--------------------------+
| 0x12+0 | 20 bits | 0x07d0, 0x0000 | Sample rate 32000 hertz |
+--------+----------+--------------------+--------------------------+
| 0x14+4 | 3 bits | 0b000 | 1 channel |
+--------+----------+--------------------+--------------------------+
| 0x14+7 | 5 bits | 0b00111 | Sample bit depth 8 bits |
+--------+----------+--------------------+--------------------------+
| 0x15+4 | 36 bits | 0b0000, 0x00000018 | Total no. of samples 24 |
+--------+----------+--------------------+--------------------------+
| 0x1a | 16 | (...) | MD5 checksum |
| | bytes | | |
+--------+----------+--------------------+--------------------------+
Table 45D.3.4. Audio Frame ๐
The frame header starts at position 0x2a, and it's broken down in the following table ๐
Okay bestie, let's get into the frame header ๐ Table 46 is the whole frame header, byte by byte, so you can see exactly where every bit lives โจ
+========+=========+=================+===================+
| Start | Length | Contents | Description |
+========+=========+=================+===================+
| 0x2a+0 | 15 bits | 0xff, 0b1111100 | Frame sync |
+--------+---------+-----------------+-------------------+
| 0x2b+7 | 1 bit | 0b0 | blocking strategy |
+--------+---------+-----------------+-------------------+
| 0x2c+0 | 4 bits | 0b0110 | 8-bit block size |
| | | | further down |
+--------+---------+-----------------+-------------------+
| 0x2c+4 | 4 bits | 0b1000 | Sample rate 32 |
| | | | kHz |
+--------+---------+-----------------+-------------------+
| 0x2d+0 | 4 bits | 0b0000 | Mono audio (1 |
| | | | channel) |
+--------+---------+-----------------+-------------------+
| 0x2d+4 | 3 bits | 0b001 | Bit depth 8 bits |
+--------+---------+-----------------+-------------------+
| 0x2d+7 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+---------+-----------------+-------------------+
| 0x2e+0 | 1 byte | 0x00 | Frame number 0 |
+--------+---------+-----------------+-------------------+
| 0x2f+0 | 1 byte | 0x17 | Block size 24 |
+--------+---------+-----------------+-------------------+
| 0x30+0 | 1 byte | 0xe9 | Frame header CRC |
+--------+---------+-----------------+-------------------+Table 46
Next up is the one and only subframe, which kicks off at byte 0x31 ๐ Table 47 shows it without the coded residual, so the predictor settings get their own spotlight ๐ฆ
+========+========+==========+=====================+
| Start | Length | Contents | Description |
+========+========+==========+=====================+
| 0x31+0 | 1 bit | 0b0 | Mandatory 0 bit |
+--------+--------+----------+---------------------+
| 0x31+1 | 6 bits | 0b100010 | Linear prediction |
| | | | subframe, 3rd order |
+--------+--------+----------+---------------------+
| 0x31+7 | 1 bit | 0b0 | No wasted bits used |
+--------+--------+----------+---------------------+
| 0x32+0 | 8 bits | 0x00 | Unencoded warm-up |
| | | | sample 0 |
+--------+--------+----------+---------------------+
| 0x33+0 | 8 bits | 0x4f | Unencoded warm-up |
| | | | sample 79 |
+--------+--------+----------+---------------------+
| 0x34+0 | 8 bits | 0x6f | Unencoded warm-up |
| | | | sample 111 |
+--------+--------+----------+---------------------+
| 0x35+0 | 4 bits | 0b0011 | Coefficient |
| | | | precision 4 bit |
+--------+--------+----------+---------------------+
| 0x35+4 | 5 bits | 0b00010 | Prediction right |
| | | | shift 2 |
+--------+--------+----------+---------------------+
| 0x36+1 | 4 bits | 0b0111 | Predictor |
| | | | coefficient 7 |
+--------+--------+----------+---------------------+
| 0x36+5 | 4 bits | 0b1010 | Predictor |
| | | | coefficient -6 |
+--------+--------+----------+---------------------+
| 0x37+1 | 4 bits | 0b0010 | Predictor |
| | | | coefficient 2 |
+--------+--------+----------+---------------------+Table 47
Now the coded residual, which is where the data stream keeps going ๐ธ Table 48 breaks it all down. Heads up, partitions 3 and 4 are left as an exercise for the reader ๐ (you got this, babe ๐ )
+========+========+==========+======================================+
| Start | Length | Contents | Description |
+========+========+==========+======================================+
| 0x37+5 | 2 bits | 0b00 | Rice-coded residual, |
| | | | 4-bit parameter |
+--------+--------+----------+--------------------------------------+
| 0x37+7 | 4 bits | 0b0010 | Partition order 2 |
+--------+--------+----------+--------------------------------------+
| 0x38+3 | 4 bits | 0b0011 | Rice parameter 3 |
+--------+--------+----------+--------------------------------------+
| 0x38+7 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+----------+--------------------------------------+
| 0x39+0 | 3 bits | 0b110 | Remainder 6 |
+--------+--------+----------+--------------------------------------+
| 0x39+3 | 1 bit | 0b1 | Quotient 0 |
+--------+--------+----------+--------------------------------------+
| 0x39+4 | 3 bits | 0b001 | Remainder 1 |
+--------+--------+----------+--------------------------------------+
| 0x39+7 | 4 bits | 0b0001 | Quotient 3 |
+--------+--------+----------+--------------------------------------+
| 0x3a+3 | 3 bits | 0b001 | Remainder 1 |
+--------+--------+----------+--------------------------------------+
| 0x3a+6 | 4 bits | 0b1111 | No Rice parameter, |
| | | | escape code |
+--------+--------+----------+--------------------------------------+
| 0x3b+2 | 5 bits | 0b00101 | Partition encoded |
| | | | with 5 bits |
+--------+--------+----------+--------------------------------------+
| 0x3b+7 | 5 bits | 0b10110 | Residual -10 |
+--------+--------+----------+--------------------------------------+
| 0x3c+4 | 5 bits | 0b11010 | Residual -6 |
+--------+--------+----------+--------------------------------------+
| 0x3d+1 | 5 bits | 0b00010 | Residual 2 |
+--------+--------+----------+--------------------------------------+
| 0x3d+6 | 5 bits | 0b01000 | Residual 8 |
+--------+--------+----------+--------------------------------------+
| 0x3e+3 | 5 bits | 0b01000 | Residual 8 |
+--------+--------+----------+--------------------------------------+
| 0x3f+0 | 5 bits | 0b00110 | Residual 6 |
+--------+--------+----------+--------------------------------------+
| 0x3f+5 | 4 bits | 0b0010 | Rice parameter 2 |
+--------+--------+----------+--------------------------------------+
| 0x40+1 | 22 | (...) | Residual partition 3 |
| | bits | | |
+--------+--------+----------+--------------------------------------+
| 0x42+7 | 4 bits | 0b0001 | Rice parameter 1 |
+--------+--------+----------+--------------------------------------+
| 0x43+3 | 23 | (...) | Residual partition 4 |
| | bits | | |
+--------+--------+----------+--------------------------------------+Table 48
The frame wraps up with 6 padding bits and a 2-byte frame CRC ๐
Okay, real talk, this subframe is a whole vibe. To decode it you calculate 21 predictions and add each one to its matching residual ๐ง The catch is that every prediction leans on the samples before it, so you can't jump in halfway through a subframe, and you can't split it up across parallel threads either ๐ญ It's strictly one after another, no skipping the line ๐
The next table breaks down the math for each sample โจ Look at row 4 as an example. Its predictor, before any shift, comes from the three warm-up samples: 7*111 - 6*79 + 2*0 = 303. Then we shift that right by 2 bits: 303 >> 2 = 75. Last step, we add the decoded residual: 75 + 3 = 78 ๐ Main character decoding energy, fr fr ๐
+===========+=====================+===========+==============+
| Residual | Predictor w/o Shift | Predictor | Sample Value |
+===========+=====================+===========+==============+
| (warm-up) | N/A | N/A | 0 |
+-----------+---------------------+-----------+--------------+
| (warm-up) | N/A | N/A | 79 |
+-----------+---------------------+-----------+--------------+
| (warm-up) | N/A | N/A | 111 |
+-----------+---------------------+-----------+--------------+
| 3 | 303 | 75 | 78 |
+-----------+---------------------+-----------+--------------+
| -1 | 38 | 9 | 8 |
+-----------+---------------------+-----------+--------------+
| -13 | -190 | -48 | -61 |
+-----------+---------------------+-----------+--------------+
| -10 | -319 | -80 | -90 |
+-----------+---------------------+-----------+--------------+
| -6 | -248 | -62 | -68 |
+-----------+---------------------+-----------+--------------+
| 2 | -58 | -15 | -13 |
+-----------+---------------------+-----------+--------------+
| 8 | 137 | 34 | 42 |
+-----------+---------------------+-----------+--------------+
| 8 | 236 | 59 | 67 |
+-----------+---------------------+-----------+--------------+
| 6 | 191 | 47 | 53 |
+-----------+---------------------+-----------+--------------+
| 0 | 53 | 13 | 13 |
+-----------+---------------------+-----------+--------------+
| -3 | -93 | -24 | -27 |
+-----------+---------------------+-----------+--------------+
| -5 | -161 | -41 | -46 |
+-----------+---------------------+-----------+--------------+
| -4 | -134 | -34 | -38 |
+-----------+---------------------+-----------+--------------+
| -1 | -44 | -11 | -12 |
+-----------+---------------------+-----------+--------------+
| 1 | 52 | 13 | 14 |
+-----------+---------------------+-----------+--------------+
| 1 | 94 | 23 | 24 |
+-----------+---------------------+-----------+--------------+
| 4 | 60 | 15 | 19 |
+-----------+---------------------+-----------+--------------+
| 2 | 17 | 4 | 6 |
+-----------+---------------------+-----------+--------------+
| 2 | -24 | -6 | -4 |
+-----------+---------------------+-----------+--------------+
| 2 | -26 | -7 | -5 |
+-----------+---------------------+-----------+--------------+
| 0 | 1 | 0 | 0 |
+-----------+---------------------+-----------+--------------+Table 49 โจ
Okay so, bestie, lining up all these samples gives us the input for the MD5 checksum calculation process ๐งฎ๐:
0x004F 6F4E 08C3 A6BC F32A 4335 0DE5 D2DA F40E 1813 06FC FB00And this literally results in the MD5 checksum we found in the streaminfo metadata block. Periodt, the math checks out ๐ ๐
Acknowledgments ๐ธ
FLAC owes so much to the many people who have pushed the audio compression field forward, and they did it so freely too ๐ซถ Here are some of the legends:
- Tony Robinson: He worked on Shorten, and his paper (see [Robinson-TR156]) is a good starting point on some of the basic methods FLAC uses. Honestly, FLAC just trivially extends and improves the fixed predictors, LPC coefficient quantization, and Rice coding that were used in Shorten. Iconic ๐
- Solomon W. Golomb and Robert F. Rice: Their universal codes are used by FLAC's entropy coder. See [Rice]. The codes are giving pure genius ๐ง โจ
- Norman Levinson and James Durbin: The FLAC reference encoder uses an algorithm they developed and refined for determining the LPC coefficients from the autocorrelation coefficients. See [Durbin]). Main character energy for real ๐ฆ
- Claude Shannon: See [Shannon]. Obviously, the GOAT of information theory ๐
The FLAC format, the FLAC reference implementation [FLAC-implementation], and the initial draft version of this document were originally developed by Josh Coalson. Many others have contributed since, but this original effort is deeply, deeply appreciated ๐ฅน๐
Authors' Addresses ๐ฆ
Martijn van Beurden Netherlands Email: mvanb1@gmail.com
Andrew Weaver Email: theandrewjw@gmail.com
๐ฆ where this page comes from
- ietf: rfc9639 2024-12
- ๐ girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms