// decodeVerbatim reads the unencoded audio samples of the subframe.
//
// ref: https://www.xiph.org/flac/format.html#subframe_verbatim
func (subframe *Subframe) decodeVerbatim(br *bits.Reader, bps uint) error {
// Parse the unencoded audio samples of the subframe.
for i := 0; i < subframe.NSamples; i++ {
// (bits-per-sample) bits: Unencoded constant value of the subblock.
x, err := br.Read(bps)
if err != nil {
return unexpected(err)
}
sample := signExtend(x, bps)
subframe.Samples = append(subframe.Samples, sample)
}
return nil
}
// decodeConstant reads an unencoded audio sample of the subframe. Each sample
// of the subframe has this constant value. The constant encoding can be thought
// of as run-length encoding.
//
// ref: https://www.xiph.org/flac/format.html#subframe_constant
func (subframe *Subframe) decodeConstant(br *bits.Reader, bps uint) error {
// (bits-per-sample) bits: Unencoded constant value of the subblock.
x, err := br.Read(bps)
if err != nil {
return unexpected(err)
}
// Each sample of the subframe has the same constant value.
sample := signExtend(x, bps)
for i := 0; i < subframe.NSamples; i++ {
subframe.Samples = append(subframe.Samples, sample)
}
return nil
}
// decodeRiceResidual decodes a Rice encoded residual (error signal).
func (subframe *Subframe) decodeRiceResidual(br *bits.Reader, k uint) error {
// Read unary encoded most significant bits.
high, err := br.ReadUnary()
if err != nil {
return unexpected(err)
}
// Read binary encoded least significant bits.
low, err := br.Read(k)
if err != nil {
return unexpected(err)
}
residual := int32(high<<k | low)
// ZigZag decode.
residual = bits.ZigZag(residual)
subframe.Samples = append(subframe.Samples, residual)
return nil
}
// decodeResidual decodes the encoded residuals (prediction method error
// signals) of the subframe.
//
// ref: https://www.xiph.org/flac/format.html#residual
func (subframe *Subframe) decodeResidual(br *bits.Reader) error {
// 2 bits: Residual coding method.
x, err := br.Read(2)
if err != nil {
return unexpected(err)
}
// The 2 bits are used to specify the residual coding method as follows:
// 00: Rice coding with a 4-bit Rice parameter.
// 01: Rice coding with a 5-bit Rice parameter.
// 10: reserved.
// 11: reserved.
switch x {
case 0x0:
return subframe.decodeRicePart(br, 4)
case 0x1:
return subframe.decodeRicePart(br, 5)
default:
return fmt.Errorf("frame.Subframe.decodeResidual: reserved residual coding method bit pattern (%02b)", x)
}
}
// decodeFIR decodes the linear prediction coded samples of the subframe, using
// polynomial coefficients stored in the stream.
//
// ref: https://www.xiph.org/flac/format.html#subframe_lpc
func (subframe *Subframe) decodeFIR(br *bits.Reader, bps uint) error {
// Parse unencoded warm-up samples.
for i := 0; i < subframe.Order; i++ {
// (bits-per-sample) bits: Unencoded warm-up sample.
x, err := br.Read(bps)
if err != nil {
return unexpected(err)
}
sample := signExtend(x, bps)
subframe.Samples = append(subframe.Samples, sample)
}
// 4 bits: (coefficients' precision in bits) - 1.
x, err := br.Read(4)
if err != nil {
return unexpected(err)
}
if x == 0xF {
return errors.New("frame.Subframe.decodeFIR: invalid coefficient precision bit pattern (1111)")
}
prec := uint(x) + 1
// 5 bits: predictor coefficient shift needed in bits.
x, err = br.Read(5)
if err != nil {
return unexpected(err)
}
shift := signExtend(x, 5)
// Parse coefficients.
coeffs := make([]int32, subframe.Order)
for i := range coeffs {
// (prec) bits: Predictor coefficient.
x, err = br.Read(prec)
if err != nil {
return unexpected(err)
}
coeffs[i] = signExtend(x, prec)
}
// Decode subframe residuals.
if err = subframe.decodeResidual(br); err != nil {
return err
}
// Predict the audio samples of the subframe using a polynomial with
// predefined coefficients of a given order. Correct signal errors using the
// decoded residuals.
return subframe.decodeLPC(coeffs, shift)
}
// decodeFixed decodes the linear prediction coded samples of the subframe,
// using a fixed set of predefined polynomial coefficients.
//
// ref: https://www.xiph.org/flac/format.html#subframe_fixed
func (subframe *Subframe) decodeFixed(br *bits.Reader, bps uint) error {
// Parse unencoded warm-up samples.
for i := 0; i < subframe.Order; i++ {
// (bits-per-sample) bits: Unencoded warm-up sample.
x, err := br.Read(bps)
if err != nil {
return unexpected(err)
}
sample := signExtend(x, bps)
subframe.Samples = append(subframe.Samples, sample)
}
// Decode subframe residuals.
err := subframe.decodeResidual(br)
if err != nil {
return err
}
// Predict the audio samples of the subframe using a polynomial with
// predefined coefficients of a given order. Correct signal errors using the
// decoded residuals.
return subframe.decodeLPC(fixedCoeffs[subframe.Order], 0)
}
// parseHeader reads and parses the header of a subframe.
func (subframe *Subframe) parseHeader(br *bits.Reader) error {
// 1 bit: zero-padding.
x, err := br.Read(1)
if err != nil {
return unexpected(err)
}
if x != 0 {
return errors.New("frame.Subframe.parseHeader: non-zero padding")
}
// 6 bits: Pred.
x, err = br.Read(6)
if err != nil {
return unexpected(err)
}
// The 6 bits are used to specify the prediction method and order as follows:
// 000000: Constant prediction method.
// 000001: Verbatim prediction method.
// 00001x: reserved.
// 0001xx: reserved.
// 001xxx:
// if (xxx <= 4)
// Fixed prediction method; xxx=order
// else
// reserved.
// 01xxxx: reserved.
// 1xxxxx: FIR prediction method; xxxxx=order-1
switch {
case x < 1:
// 000000: Constant prediction method.
subframe.Pred = PredConstant
case x < 2:
// 000001: Verbatim prediction method.
subframe.Pred = PredVerbatim
case x < 8:
// 00001x: reserved.
// 0001xx: reserved.
return fmt.Errorf("frame.Subframe.parseHeader: reserved prediction method bit pattern (%06b)", x)
case x < 16:
// 001xxx:
// if (xxx <= 4)
// Fixed prediction method; xxx=order
// else
// reserved.
order := int(x & 0x07)
if order > 4 {
return fmt.Errorf("frame.Subframe.parseHeader: reserved prediction method bit pattern (%06b)", x)
}
subframe.Pred = PredFixed
subframe.Order = order
case x < 32:
// 01xxxx: reserved.
return fmt.Errorf("frame.Subframe.parseHeader: reserved prediction method bit pattern (%06b)", x)
default:
// 1xxxxx: FIR prediction method; xxxxx=order-1
subframe.Pred = PredFIR
subframe.Order = int(x&0x1F) + 1
}
// 1 bit: hasWastedBits.
x, err = br.Read(1)
if err != nil {
return unexpected(err)
}
if x != 0 {
// k wasted bits-per-sample in source subblock, k-1 follows, unary coded;
// e.g. k=3 => 001 follows, k=7 => 0000001 follows.
x, err = br.ReadUnary()
if err != nil {
return unexpected(err)
}
subframe.Wasted = uint(x) + 1
}
return nil
}
// decodeRicePart decodes a Rice partition of encoded residuals from the
// subframe, using a Rice parameter of the specified size in bits.
//
// ref: https://www.xiph.org/flac/format.html#partitioned_rice
// ref: https://www.xiph.org/flac/format.html#partitioned_rice2
func (subframe *Subframe) decodeRicePart(br *bits.Reader, paramSize uint) error {
// 4 bits: Partition order.
x, err := br.Read(4)
if err != nil {
return unexpected(err)
}
partOrder := x
// Parse Rice partitions; in total 2^partOrder partitions.
//
// ref: https://www.xiph.org/flac/format.html#rice_partition
// ref: https://www.xiph.org/flac/format.html#rice2_partition
nparts := 1 << partOrder
for i := 0; i < nparts; i++ {
// (4 or 5) bits: Rice parameter.
x, err = br.Read(paramSize)
if err != nil {
return unexpected(err)
}
param := uint(x)
// Determine the number of Rice encoded samples in the partition.
var nsamples int
if partOrder == 0 {
nsamples = subframe.NSamples - subframe.Order
} else if i != 0 {
nsamples = subframe.NSamples / nparts
} else {
nsamples = subframe.NSamples/nparts - subframe.Order
}
// TODO(u): Verify that decoding of subframes with Rice parameter escape
// codes have been implemented correctly.
if paramSize == 4 && param == 0xF || paramSize == 5 && param == 0x1F {
// 1111 or 11111: Escape code, meaning the partition is in unencoded
// binary form using n bits per sample; n follows as a 5-bit number.
x, err := br.Read(5)
if err != nil {
return unexpected(err)
}
n := uint(x)
for j := 0; j < nsamples; j++ {
sample, err := br.Read(n)
if err != nil {
return unexpected(err)
}
subframe.Samples = append(subframe.Samples, int32(sample))
}
// TODO(u): Remove log message when the test cases have been extended.
log.Print("frame.Subframe.decodeRicePart: The flac library test cases do not yet include any audio files with Rice parameter escape codes. If possible please consider contributing this audio sample to improve the reliability of the test cases.")
return nil
}
// Decode the Rice encoded residuals of the partition.
for j := 0; j < nsamples; j++ {
if err = subframe.decodeRiceResidual(br, param); err != nil {
return err
}
}
}
return nil
}