0
@@ -6,6 +6,7 @@
0
 .\"171 Second Street, Suite 300,
0
 .\"San Francisco, California, 94105, USA.
0
 .SUBSECTION "FLAC decoding"
0
+.nr ZF \n%
0
 .PP
0
 A FLAC stream is made up of individual FLAC frames, as follows:
0
 .begin dformat
0
@@ -476,19 +477,137 @@ the subframe.
0
 .bp
0
 .SUBSECTION "FLAC encoding"
0
 .PP
0
-Until this point, the discussion of FLAC has assumed one has a FLAC file
0
-and wishes to extracted decoded PCM data from it.
0
-This process requires a broad knowledge of the format, since
0
-a single FLAC file created by the reference encoder is likely to use a
0
-wide variety of frame types, predictor orders, partition orders, and so
0
-forth.
0
-Conversely, encoding a FLAC file from PCM data requires only as much
0
-of the format as you wish;
0
-so long as the headers are correct, one can generate a perfectly
0
-valid FLAC file containing nothing but verbatim subframes, for example.
0
-But in order to generate useful compression, a deeper analysis of one's
0
-input PCM is needed.
0
-.PP
0
 For the purposes of discussing FLAC encoding,
0
 we'll assume one has a stream of input PCM values along with the
0
 stream's sample rate, number of channels and bits per sample.
0
+Creating a valid FLAC file is then a matter of writing the proper
0
+file header, metadata blocks and FLAC frames.
0
+.begin dformat
0
+style bitwid 0.08
0
+style charwid 0
0
+style recspread 0.15
0
+noname
0
+       0-31-24 Header (`fLaC' 0x664C6143)
0
+  FD1: 32--8 @roman Metadata sub 1@
0
+       --8 @roman Metadata sub 2@
0
+       --8-dashed ...
0
+  FD2: --8 @roman Frame sub 1@
0
+       --8 @roman Frame sub 2@
0
+       --8-dashed ...
0
+noname
0
+  FD3: 0-31-16 Metadata Header
0
+  FD4: 32--16-dashed Block Data
0
+       --4-invis
0
+  FD5: 0-48/128-14 Frame Header
0
+  FD7: --8 @roman Subframe sub 1@
0
+       --8 @roman Subframe sub 2@
0
+       --4-dashed ...
0
+  FD6: --6 CRC-16
0
+noname
0
+        --38-invis
0
+  FD8:  0-7-16 Subframe Header
0
+  FD9:  8--21 Subframe data
0
+pic line dotted from FD1.sw to FD3.nw
0
+pic line dotted from FD1.se to FD4.ne
0
+pic line dotted from FD2.sw to FD5.nw
0
+pic line dotted from FD2.se to FD6.ne
0
+pic line dotted from FD7.sw to FD8.nw
0
+pic line dotted from FD7.se to FD9.ne
0
+.end dformat
0
+.SUBSUBSECTION "Metadata header"
0
+.PP
0
+.TS
0
+tab(:);
0
+| c | c |
0
+| r | l |.
0
+_
0
+bits:value
0
+=
0
+1:0 if addition metadata blocks follow, 1 if not
0
+7:0 for STREAMINFO, 1 for PADDING, 4 for VORBIS_COMMENT, etc.
0
+24:the length of the block data in bytes, not including the header
0
+_
0
+.TE
0
+.SUBSUBSECTION "the STREAMINFO metadata block"
0
+.PP
0
+.TS
0
+tab(:);
0
+| c | c |
0
+| r | l |.
0
+_
0
+bits:value
0
+=
0
+16:the minimum FLAC frame size, in PCM frames
0
+16:the maximum FLAC frame size, in PCM frames
0
+24:the minimum FLAC frame size, in bytes
0
+24:the maximum FLAC frame size, in bytes
0
+20:the stream's sample rate, in Hz
0
+3:the stream's channel count, minus one
0
+5:the stream's bit-per-sample, minus one
0
+36:the stream's total number of PCM frames
0
+128:an MD5 sum of the PCM stream's bytes
0
+_
0
+.TE
0
+.PP
0
+When encoding a FLAC file, many of these fields cannot be known in advance.
0
+Instead, one must keep track of those values during encoding and then
0
+rewrite the STREAMINFO block when finished.
0
+.SUBSUBSECTION "the VORBIS_COMMENT metadata block"
0
+.PP
0
+.TS
0
+tab(:);
0
+| c | c |
0
+| r | l |.
0
+_
0
+bits:value
0
+=
0
+32\[dd]:vendor string length, in bytes
0
+string length * 8:vendor string data, as UTF-8 encoded text
0
+32\[dd]:total number of comment strings
0
+32\[dd]:comment @roman string sub 1@ length, in bytes
0
+string length * 8:comment @roman string sub 1@, as UTF-8 encoded text
0
+ ...:...
0
+_
0
+.TE
0
+.PP
0
+Fields marked with \[dd] are little-endian integers.
0
+.SUBSUBSECTION "the PADDING metadata block"
0
+.PP
0
+This is simply an empty block full of \fC0x00\fR bytes.
0
+.bp
0
+.SUBSUBSECTION "Frame header"
0
+.PP
0
+.TS
0
+tab(:);
0
+| c | c |
0
+| r | l |.
0
+_
0
+bits:value
0
+=
0
+14:\fC0x3FFE\fR sync code
0
+1:\fC0\fR reserved
0
+1:\fC0\fR if the header encodes the frame number, \fC1\fR if it encodes the sample number
0
+4:this frame's block size, as encoded PCM frames\(dg
0
+4:this frame's sample rate, as encoded Hz\(dg
0
+4:this frame's channel assignment\(dg
0
+3:this frame's bits per sample\(dg
0
+1:\fC0\fR padding
0
+8-56:the frame number, or sample number, UTF-8 encoded and starting from 0
0
+0/8/16:the number of PCM frames (minus one) in this FLAC frame, if block size is \fC0x6\fR (8 bits) or \fC0x7\fR (16 bits)
0
+0/8/16:the sample rate of this FLAC frame, if sample rate is \fC0xC\fR (8 bits), \fC0xD\fR (16 bits) or \fC0xE\fR (16 bits)
0
+8:the CRC-8 of all data from the beginning of the frame header
0
+_
0
+.TE
0
+.FS
0
+\(dg See table on page \n(ZF
0
+.FE
0
+.PP
0
+The FLAC frame's block size in PCM frames
0
+(called ``channel independent samples'' in FLAC's documention)
0
+is typically encoded in the 4 bit `block size' field.
0
+But for odd-sized frames - which often occur at the end of the stream -
0
+that value is stored as an 8 or 16 bit integer following UTF-8 encoded
0
+frame number.
0
+Less commonly, odd sample rate values are stored as 8 bit (in kHz),
0
+16 bit (in Hz) or 16 bit (in 10s of Hz) prior to the CRC-8,
0
+should a predefined value not be available.

0
@@ -1,9 +1,9 @@
0
-.\"This work is licensed under the 
0
+.\"This work is licensed under the
0
 .\"Creative Commons Attribution-Share Alike 3.0 United States License.
0
 .\"To view a copy of this license, visit
0
-.\"http://creativecommons.org/licenses/by-sa/3.0/us/ or send a letter to 
0
-.\"Creative Commons, 
0
-.\"171 Second Street, Suite 300, 
0
+.\"http://creativecommons.org/licenses/by-sa/3.0/us/ or send a letter to
0
+.\"Creative Commons,
0
+.\"171 Second Street, Suite 300,
0
 .\"San Francisco, California, 94105, USA.
0
 .SECTION "FLAC"
0
 .PP
0
@@ -12,7 +12,7 @@ It compresses PCM audio data losslessly using predictors and a residual.
0
 FLACs are smaller than WAVEs, contain checksumming to verify their
0
 integrity, contain comment tags for metadata and are streamable.
0
 .PP
0
-Except for the contents of the VORBIS_COMMENT metadata block, 
0
+Except for the contents of the VORBIS_COMMENT metadata block,
0
 everything in FLAC is big-endian.
0
 
0
 .SUBSECTION "the FLAC file stream"
0
@@ -197,7 +197,7 @@ pic line dotted from D1.se to D3.ne
0
 .ps 8
0
 .TS
0
 tab(:);
0
-| c s s s | 
0
+| c s s s |
0
 | r | l || r | l |.
0
 _
0
 Picture Types