diff --git a/codec/adpcm/adpcm.go b/codec/adpcm/adpcm.go index 595728a2..ce8ae9f7 100644 --- a/codec/adpcm/adpcm.go +++ b/codec/adpcm/adpcm.go @@ -2,9 +2,6 @@ NAME adpcm.go -DESCRIPTION - adpcm.go contains functions for encoding/compressing pcm into adpcm and decoding/decompressing back to pcm. - AUTHOR Trek Hopton @@ -30,40 +27,25 @@ LICENSE Reference algorithms for ADPCM compression and decompression are in part 6. */ +// Package adpcm provides functions to transcode between PCM and ADPCM. package adpcm import ( - "bytes" "encoding/binary" "fmt" + "io" + "math" ) -// encoder is used to encode to ADPCM from PCM data. -// pred and index hold state that persists between calls to encodeSample and calcHead. -// dest is the output buffer that implements io.writer and io.bytewriter, ie. where the encoded ADPCM data is written to. -type encoder struct { - dest *bytes.Buffer - pred int16 - index int16 -} - -// decoder is used to decode from ADPCM to PCM data. -// pred, index, and step hold state that persists between calls to decodeSample. -// dest is the output buffer that implements io.writer and io.bytewriter, ie. where the decoded PCM data is written to. -type decoder struct { - dest *bytes.Buffer - pred int16 - index int16 - step int16 -} - -// PcmBS is the size of the blocks that an encoder uses. -// 'encodeBlock' will encode PcmBS bytes at a time and the output will be AdpcmBS bytes long. -const PcmBS = 1010 - -// AdpcmBS is the size of the blocks that a decoder uses. -// 'decodeBlock' will decode AdpcmBS bytes at a time and the output will be PcmBS bytes long. -const AdpcmBS = 256 +const ( + byteDepth = 2 // We are working with 16-bit samples. TODO(Trek): make configurable. + initSamps = 2 // Number of samples used to initialise the encoder. + initBytes = initSamps * byteDepth + headBytes = 4 // Number of bytes in the header of ADPCM. + samplesPerEnc = 2 // Number of sample encoded at a time eg. 2 16-bit samples get encoded into 1 byte. + bytesPerEnc = samplesPerEnc * byteDepth + compFact = 4 // In general ADPCM compresses by a factor of 4. +) // Table of index changes (see spec). var indexTable = []int16{ @@ -87,28 +69,35 @@ var stepTable = []int16{ 32767, } -// NewEncoder retuns a new ADPCM encoder. -func NewEncoder(dst *bytes.Buffer) *encoder { - e := encoder{ - dest: dst, - } - return &e +// Encoder is used to encode to ADPCM from PCM data. +type Encoder struct { + // dst is the destination for ADPCM-encoded data. + dst io.Writer + + est int16 // Estimation of sample based on quantised ADPCM nibble. + idx int16 // Index to step used for estimation. } -// NewDecoder retuns a new ADPCM decoder. -func NewDecoder(dst *bytes.Buffer) *decoder { - d := decoder{ - step: stepTable[0], - dest: dst, - } - return &d +// Decoder is used to decode from ADPCM to PCM data. +type Decoder struct { + // dst is the destination for PCM-encoded data. + dst io.Writer + + est int16 // Estimation of sample based on quantised ADPCM nibble. + idx int16 // Index to step used for estimation. + step int16 +} + +// NewEncoder retuns a new ADPCM Encoder. +func NewEncoder(dst io.Writer) *Encoder { + return &Encoder{dst: dst} } // encodeSample takes a single 16 bit PCM sample and // returns a byte of which the last 4 bits are an encoded ADPCM nibble. -func (e *encoder) encodeSample(sample int16) byte { - // Find difference of actual sample from encoder's prediction. - delta := sample - e.pred +func (e *Encoder) encodeSample(sample int16) byte { + // Find difference between the sample and the previous estimation. + delta := capAdd16(sample, -e.est) // Create and set sign bit for nibble and find absolute value of difference. var nib byte @@ -117,217 +106,250 @@ func (e *encoder) encodeSample(sample int16) byte { delta = -delta } - step := stepTable[e.index] + step := stepTable[e.idx] diff := step >> 3 var mask byte = 4 for i := 0; i < 3; i++ { if delta > step { nib |= mask - delta -= step - diff += step + delta = capAdd16(delta, -step) + diff = capAdd16(diff, step) } mask >>= 1 step >>= 1 } - // Adjust predicted sample based on calculated difference. if nib&8 != 0 { - e.pred -= diff - } else { - e.pred += diff + diff = -diff } - e.index += indexTable[nib&7] + // Adjust estimated sample based on calculated difference. + e.est = capAdd16(e.est, diff) + + e.idx += indexTable[nib&7] // Check for underflow and overflow. - if e.index < 0 { - e.index = 0 - } else if e.index > int16(len(stepTable)-1) { - e.index = int16(len(stepTable) - 1) + if e.idx < 0 { + e.idx = 0 + } else if e.idx > int16(len(stepTable)-1) { + e.idx = int16(len(stepTable) - 1) } return nib } +// calcHead sets the state for the Encoder by running the first sample through +// the Encoder, and writing the first sample to the Encoder's io.Writer (dst). +// It returns the number of bytes written to the Encoder's destination and the first error encountered. +func (e *Encoder) calcHead(sample []byte, pad bool) (int, error) { + // Check that we are given 1 sample. + if len(sample) != byteDepth { + return 0, fmt.Errorf("length of given byte array is: %v, expected: %v", len(sample), byteDepth) + } + + n, err := e.dst.Write(sample) + if err != nil { + return n, err + } + + _n, err := e.dst.Write([]byte{byte(int16(e.idx))}) + if err != nil { + return n, err + } + n += _n + + if pad { + _n, err = e.dst.Write([]byte{0x01}) + } else { + _n, err = e.dst.Write([]byte{0x00}) + } + n += _n + if err != nil { + return n, err + } + return n, nil +} + +// init initializes the Encoder's estimation to the first uncompressed sample and the index to +// point to a suitable quantizer step size. +// The suitable step size is the closest step size in the stepTable to half the absolute difference of the first two samples. +func (e *Encoder) init(samples []byte) { + int1 := int16(binary.LittleEndian.Uint16(samples[:byteDepth])) + int2 := int16(binary.LittleEndian.Uint16(samples[byteDepth:initBytes])) + e.est = int1 + + halfDiff := math.Abs(math.Abs(float64(int1)) - math.Abs(float64(int2))/2) + closest := math.Abs(float64(stepTable[0]) - halfDiff) + var cInd int16 + for i, step := range stepTable { + if math.Abs(float64(step)-halfDiff) < closest { + closest = math.Abs(float64(step) - halfDiff) + cInd = int16(i) + } + } + e.idx = cInd +} + +// Write takes a slice of bytes of arbitrary length representing pcm and encodes it into adpcm. +// It writes its output to the Encoder's dst. +// The number of bytes written out is returned along with any error that occured. +func (e *Encoder) Write(b []byte) (int, error) { + // Check that pcm has enough data to initialize Decoder. + pcmLen := len(b) + if pcmLen < initBytes { + return 0, fmt.Errorf("length of given byte array must be >= %v", initBytes) + } + + // Determine if there will be a byte that won't contain two full nibbles and will need padding. + pad := false + if (pcmLen-byteDepth)%bytesPerEnc != 0 { + pad = true + } + + e.init(b[:initBytes]) + n, err := e.calcHead(b[:byteDepth], pad) + if err != nil { + return n, err + } + // Skip the first sample and start at the end of the first two samples, then every two samples encode them into a byte of adpcm. + for i := byteDepth; i+bytesPerEnc-1 < pcmLen; i += bytesPerEnc { + nib1 := e.encodeSample(int16(binary.LittleEndian.Uint16(b[i : i+byteDepth]))) + nib2 := e.encodeSample(int16(binary.LittleEndian.Uint16(b[i+byteDepth : i+bytesPerEnc]))) + _n, err := e.dst.Write([]byte{byte((nib2 << 4) | nib1)}) + n += _n + if err != nil { + return n, err + } + } + // If we've reached the end of the pcm data and there's a sample left over, + // compress it to a nibble and leave the first half of the byte padded with 0s. + if pad { + nib := e.encodeSample(int16(binary.LittleEndian.Uint16(b[pcmLen-byteDepth : pcmLen]))) + _n, err := e.dst.Write([]byte{nib}) + n += _n + if err != nil { + return n, err + } + } + return n, nil +} + +// NewDecoder retuns a new ADPCM Decoder. +func NewDecoder(dst io.Writer) *Decoder { + return &Decoder{dst: dst} +} + // decodeSample takes a byte, the last 4 bits of which contain a single // 4 bit ADPCM nibble, and returns a 16 bit decoded PCM sample. -func (d *decoder) decodeSample(nibble byte) int16 { +func (d *Decoder) decodeSample(nibble byte) int16 { // Calculate difference. var diff int16 if nibble&4 != 0 { - diff += d.step + diff = capAdd16(diff, d.step) } if nibble&2 != 0 { - diff += d.step >> 1 + diff = capAdd16(diff, d.step>>1) } if nibble&1 != 0 { - diff += d.step >> 2 + diff = capAdd16(diff, d.step>>2) } - diff += d.step >> 3 + diff = capAdd16(diff, d.step>>3) // Account for sign bit. if nibble&8 != 0 { diff = -diff } - // Adjust predicted sample based on calculated difference. - d.pred += diff + // Adjust estimated sample based on calculated difference. + d.est = capAdd16(d.est, diff) // Adjust index into step size lookup table using nibble. - d.index += indexTable[nibble] + d.idx += indexTable[nibble] // Check for overflow and underflow. - if d.index < 0 { - d.index = 0 - } else if d.index > int16(len(stepTable)-1) { - d.index = int16(len(stepTable) - 1) + if d.idx < 0 { + d.idx = 0 + } else if d.idx > int16(len(stepTable)-1) { + d.idx = int16(len(stepTable) - 1) } // Find new quantizer step size. - d.step = stepTable[d.index] + d.step = stepTable[d.idx] - return d.pred + return d.est } -// calcHead sets the state for the encoder by running the first sample through -// the encoder, and writing the first sample to the encoder's io.Writer (dest). -// It returns the number of bytes written to the encoder's io.Writer (dest) along with any errors. -func (e *encoder) calcHead(sample []byte) (int, error) { - // Check that we are given 1 16-bit sample (2 bytes). - const sampSize = 2 - if len(sample) != sampSize { - return 0, fmt.Errorf("length of given byte array is: %v, expected: %v", len(sample), sampSize) - } - - intSample := int16(binary.LittleEndian.Uint16(sample)) - e.encodeSample(intSample) - - n, err := e.dest.Write(sample) - if err != nil { - return n, err - } - - err = e.dest.WriteByte(byte(uint16(e.index))) - if err != nil { - return n, err - } - n++ - - err = e.dest.WriteByte(byte(0x00)) - if err != nil { - return n, err - } - n++ - return n, nil -} - -// encodeBlock takes a slice of 1010 bytes (505 16-bit PCM samples). -// It writes encoded (compressed) bytes (each byte containing two ADPCM nibbles) to the encoder's io.Writer (dest). -// The number of bytes written is returned along with any errors. -// Note: nibbles are output in little endian order, eg. n1n0 n3n2 n5n4... -// Note: first 4 bytes are for initializing the decoder before decoding a block. -// - First two bytes contain the first 16-bit sample uncompressed. -// - Third byte is the decoder's starting index for the block, the fourth is padding and ignored. -func (e *encoder) encodeBlock(block []byte) (int, error) { - if len(block) != PcmBS { - return 0, fmt.Errorf("unsupported block size. Given: %v, expected: %v, ie. 505 16-bit PCM samples", len(block), PcmBS) - } - - n, err := e.calcHead(block[0:2]) - if err != nil { - return n, err - } - - for i := 3; i < PcmBS; i += 4 { - nib1 := e.encodeSample(int16(binary.LittleEndian.Uint16(block[i-1 : i+1]))) - nib2 := e.encodeSample(int16(binary.LittleEndian.Uint16(block[i+1 : i+3]))) - err = e.dest.WriteByte(byte((nib2 << 4) | nib1)) - if err != nil { - return n, err - } - n++ - } - - return n, nil -} - -// decodeBlock takes a slice of 256 bytes, each byte after the first 4 should contain two ADPCM encoded nibbles. -// It writes the resulting decoded (decompressed) 16-bit PCM samples to the decoder's io.Writer (dest). -// The number of bytes written is returned along with any errors. -func (d *decoder) decodeBlock(block []byte) (int, error) { - if len(block) != AdpcmBS { - return 0, fmt.Errorf("unsupported block size. Given: %v, expected: %v", len(block), AdpcmBS) - } - - // Initialize decoder with first 4 bytes of the block. - d.pred = int16(binary.LittleEndian.Uint16(block[0:2])) - d.index = int16(block[2]) - d.step = stepTable[d.index] - n, err := d.dest.Write(block[0:2]) +// Write takes a slice of bytes of arbitrary length representing adpcm and decodes it into pcm. +// It writes its output to the Decoder's dst. +// The number of bytes written out is returned along with any error that occured. +func (d *Decoder) Write(b []byte) (int, error) { + // Initialize Decoder with first 4 bytes of b. + d.est = int16(binary.LittleEndian.Uint16(b[:byteDepth])) + d.idx = int16(b[byteDepth]) + d.step = stepTable[d.idx] + n, err := d.dst.Write(b[:byteDepth]) if err != nil { return n, err } // For each byte, seperate it into two nibbles (each nibble is a compressed sample), // then decode each nibble and output the resulting 16-bit samples. - for i := 4; i < AdpcmBS; i++ { - twoNibs := block[i] + // If padding flag is true (Adpcm[3]), only decode up until the last byte, then decode that separately. + for i := headBytes; i < len(b)-int(b[3]); i++ { + twoNibs := b[i] nib2 := byte(twoNibs >> 4) nib1 := byte((nib2 << 4) ^ twoNibs) - firstBytes := make([]byte, 2) + firstBytes := make([]byte, byteDepth) binary.LittleEndian.PutUint16(firstBytes, uint16(d.decodeSample(nib1))) - _n, err := d.dest.Write(firstBytes) + _n, err := d.dst.Write(firstBytes) n += _n if err != nil { return n, err } - secondBytes := make([]byte, 2) + secondBytes := make([]byte, byteDepth) binary.LittleEndian.PutUint16(secondBytes, uint16(d.decodeSample(nib2))) - _n, err = d.dest.Write(secondBytes) + _n, err = d.dst.Write(secondBytes) n += _n if err != nil { return n, err } } - - return n, nil -} - -// Write takes a slice of bytes of arbitrary length representing pcm and encodes in into adpcm. -// It writes its output to the encoder's dest. -// The number of bytes written out is returned along with any error that occured. -func (e *encoder) Write(inPcm []byte) (int, error) { - numBlocks := len(inPcm) / PcmBS - n := 0 - for i := 0; i < numBlocks; i++ { - block := inPcm[PcmBS*i : PcmBS*(i+1)] - _n, err := e.encodeBlock(block) + if b[3] == 0x01 { + padNib := b[len(b)-1] + samp := make([]byte, byteDepth) + binary.LittleEndian.PutUint16(samp, uint16(d.decodeSample(padNib))) + _n, err := d.dst.Write(samp) n += _n if err != nil { return n, err } } - return n, nil } -// Write takes a slice of bytes of arbitrary length representing adpcm and decodes in into pcm. -// It writes its output to the decoder's dest. -// The number of bytes written out is returned along with any error that occured. -func (d *decoder) Write(inAdpcm []byte) (int, error) { - numBlocks := len(inAdpcm) / AdpcmBS - n := 0 - for i := 0; i < numBlocks; i++ { - block := inAdpcm[AdpcmBS*i : AdpcmBS*(i+1)] - _n, err := d.decodeBlock(block) - n += _n - if err != nil { - return n, err - } +// capAdd16 adds two int16s together and caps at max/min int16 instead of overflowing +func capAdd16(a, b int16) int16 { + c := int32(a) + int32(b) + switch { + case c < math.MinInt16: + return math.MinInt16 + case c > math.MaxInt16: + return math.MaxInt16 + default: + return int16(c) } - - return n, nil +} + +// EncBytes will return the number of adpcm bytes that will be generated when encoding the given amount of pcm bytes (n). +func EncBytes(n int) int { + // For 'n' pcm bytes, 1 sample is left uncompressed, the rest is compressed by a factor of 4 + // and a start index and padding-flag byte are added. + // Also if there are an even number of samples, there will be half a byte of padding added to the last byte. + if n%bytesPerEnc == 0 { + return (n-byteDepth)/compFact + headBytes + 1 + } + return (n-byteDepth)/compFact + headBytes } diff --git a/codec/adpcm/adpcm_test.go b/codec/adpcm/adpcm_test.go index 9df24028..8b825696 100644 --- a/codec/adpcm/adpcm_test.go +++ b/codec/adpcm/adpcm_test.go @@ -37,14 +37,13 @@ import ( // then compare the result with expected ADPCM. func TestEncodeBlock(t *testing.T) { // Read input pcm. - pcm, err := ioutil.ReadFile("../../../test/test-data/av/input/raw-voice.pcm") + pcm, err := ioutil.ReadFile("../../../test/test-data/av/input/original_8kHz_adpcm_test.pcm") if err != nil { t.Errorf("Unable to read input PCM file: %v", err) } // Encode adpcm. - numBlocks := len(pcm) / PcmBS - comp := bytes.NewBuffer(make([]byte, 0, AdpcmBS*numBlocks)) + comp := bytes.NewBuffer(make([]byte, 0, EncBytes(len(pcm)))) enc := NewEncoder(comp) _, err = enc.Write(pcm) if err != nil { @@ -52,7 +51,7 @@ func TestEncodeBlock(t *testing.T) { } // Read expected adpcm file. - exp, err := ioutil.ReadFile("../../../test/test-data/av/output/encoded-voice.adpcm") + exp, err := ioutil.ReadFile("../../../test/test-data/av/output/encoded_8kHz_adpcm_test.adpcm") if err != nil { t.Errorf("Unable to read expected ADPCM file: %v", err) } @@ -66,14 +65,13 @@ func TestEncodeBlock(t *testing.T) { // resulting PCM with the expected decoded PCM. func TestDecodeBlock(t *testing.T) { // Read adpcm. - comp, err := ioutil.ReadFile("../../../test/test-data/av/input/encoded-voice.adpcm") + comp, err := ioutil.ReadFile("../../../test/test-data/av/input/encoded_8kHz_adpcm_test.adpcm") if err != nil { t.Errorf("Unable to read input ADPCM file: %v", err) } // Decode adpcm. - numBlocks := len(comp) / AdpcmBS - decoded := bytes.NewBuffer(make([]byte, 0, PcmBS*numBlocks)) + decoded := bytes.NewBuffer(make([]byte, 0, len(comp)*4)) dec := NewDecoder(decoded) _, err = dec.Write(comp) if err != nil { @@ -81,7 +79,7 @@ func TestDecodeBlock(t *testing.T) { } // Read expected pcm file. - exp, err := ioutil.ReadFile("../../../test/test-data/av/output/decoded-voice.pcm") + exp, err := ioutil.ReadFile("../../../test/test-data/av/output/decoded_8kHz_adpcm_test.pcm") if err != nil { t.Errorf("Unable to read expected PCM file: %v", err) } diff --git a/codec/pcm/pcm.go b/codec/pcm/pcm.go index 5ead3143..bb200d50 100644 --- a/codec/pcm/pcm.go +++ b/codec/pcm/pcm.go @@ -24,6 +24,8 @@ LICENSE You should have received a copy of the GNU General Public License in gpl.txt. If not, see [GNU licenses](http://www.gnu.org/licenses). */ + +// Package pcm provides functions for processing and converting pcm audio. package pcm import ( diff --git a/exp/adpcm/decode-pcm/decode-pcm.go b/exp/adpcm/decode-pcm/decode-pcm.go index 8d2bd7f6..2d471324 100644 --- a/exp/adpcm/decode-pcm/decode-pcm.go +++ b/exp/adpcm/decode-pcm/decode-pcm.go @@ -2,9 +2,6 @@ NAME decode-pcm.go -DESCRIPTION - decode-pcm.go is a program for decoding/decompressing an adpcm file to a pcm file. - AUTHOR Trek Hopton @@ -25,6 +22,7 @@ LICENSE If not, see [GNU licenses](http://www.gnu.org/licenses). */ +// decode-pcm is a command-line program for decoding/decompressing an adpcm file to a pcm file. package main import ( @@ -54,8 +52,7 @@ func main() { fmt.Println("Read", len(comp), "bytes from file", inPath) // Decode adpcm. - numBlocks := len(comp) / adpcm.AdpcmBS - decoded := bytes.NewBuffer(make([]byte, 0, adpcm.PcmBS*numBlocks)) + decoded := bytes.NewBuffer(make([]byte, 0, len(comp)*4)) dec := adpcm.NewDecoder(decoded) _, err = dec.Write(comp) if err != nil { diff --git a/exp/adpcm/encode-pcm/encode-pcm.go b/exp/adpcm/encode-pcm/encode-pcm.go index d283c822..ded88017 100644 --- a/exp/adpcm/encode-pcm/encode-pcm.go +++ b/exp/adpcm/encode-pcm/encode-pcm.go @@ -2,9 +2,6 @@ NAME encode-pcm.go -DESCRIPTION - encode-pcm.go is a program for encoding/compressing a pcm file to an adpcm file. - AUTHOR Trek Hopton @@ -25,6 +22,7 @@ LICENSE If not, see [GNU licenses](http://www.gnu.org/licenses). */ +// encode-pcm is a command-line program for encoding/compressing a pcm file to an adpcm file. package main import ( @@ -54,8 +52,7 @@ func main() { fmt.Println("Read", len(pcm), "bytes from file", inPath) // Encode adpcm. - numBlocks := len(pcm) / adpcm.PcmBS - comp := bytes.NewBuffer(make([]byte, 0, adpcm.AdpcmBS*numBlocks)) + comp := bytes.NewBuffer(make([]byte, 0, adpcm.EncBytes(len(pcm)))) enc := adpcm.NewEncoder(comp) _, err = enc.Write(pcm) if err != nil { diff --git a/exp/pcm/resample/resample.go b/exp/pcm/resample/resample.go index eab7a342..3d595bb8 100644 --- a/exp/pcm/resample/resample.go +++ b/exp/pcm/resample/resample.go @@ -2,9 +2,6 @@ NAME resample.go -DESCRIPTION - resample.go is a program for resampling a pcm file. - AUTHOR Trek Hopton @@ -24,6 +21,8 @@ LICENSE You should have received a copy of the GNU General Public License in gpl.txt. If not, see [GNU licenses](http://www.gnu.org/licenses). */ + +// resample is a command-line program for resampling a pcm file. package main import ( diff --git a/exp/pcm/stereo-to-mono/stereo-to-mono.go b/exp/pcm/stereo-to-mono/stereo-to-mono.go index ccbf87bf..7dbfd9a5 100644 --- a/exp/pcm/stereo-to-mono/stereo-to-mono.go +++ b/exp/pcm/stereo-to-mono/stereo-to-mono.go @@ -2,9 +2,6 @@ NAME stereo-to-mono.go -DESCRIPTION - stereo-to-mono.go is a program for converting a mono pcm file to a stereo pcm file. - AUTHOR Trek Hopton @@ -24,6 +21,8 @@ LICENSE You should have received a copy of the GNU General Public License in gpl.txt. If not, see [GNU licenses](http://www.gnu.org/licenses). */ + +// stereo-to-mono is a command-line program for converting a mono pcm file to a stereo pcm file. package main import (