lc3

README

lc3

Go and browser LC3 encoder/decoder packages backed by Google liblc3.

This repository publishes two artifacts from one source tree:

• Go module: github.com/caitunai/lc3
• npm package: @caitun/lc3

The bundled liblc3 source lives in internal/csrc/liblc3, so users installing the Go module do not need git submodules.

Go

Install:

go get github.com/caitunai/lc3

Encode and decode one LC3 frame:

package main

import "github.com/caitunai/lc3"

func main() {
	encoder, err := lc3.NewEncoder(lc3.Config{
		SampleRate:      16000,
		FrameDurationUS: 10000,
		Bitrate:         32000,
	})
	if err != nil {
		panic(err)
	}
	defer encoder.Close()

	pcm := make([]float32, encoder.FrameSize())
	frame, err := encoder.Encode(pcm)
	if err != nil {
		panic(err)
	}

	decoder, err := lc3.NewDecoder(lc3.Config{
		SampleRate:      16000,
		FrameDurationUS: 10000,
		FrameBytes:      len(frame),
	})
	if err != nil {
		panic(err)
	}
	defer decoder.Close()

	decoded, err := decoder.Decode(frame)
	if err != nil {
		panic(err)
	}
	_ = decoded
}

The Go package uses cgo. With CGO_ENABLED=0, constructors return ErrInit and the package still compiles.

Browser

Install:

npm install @caitun/lc3

Use:

import { LC3Encoder, LC3Decoder } from '@caitun/lc3'

const encoder = await LC3Encoder.create({
  sampleRate: 16000,
  frameDurationUs: 10000,
  bitrate: 32000
})

const pcm = new Float32Array(encoder.frameSize)
const frame = encoder.encode(pcm)
encoder.close()

const decoder = await LC3Decoder.create({
  sampleRate: 16000,
  frameDurationUs: 10000,
  frameBytes: frame.byteLength
})

const decoded = decoder.decode(frame)
decoder.close()

The npm package includes prebuilt Emscripten WASM files under dist/wasm.

Build

Go:

go test ./...
CGO_ENABLED=0 go test ./...

Browser:

cd packages/browser
npm run build
npm test

npm run build:wasm requires Emscripten emcc.

Release

The Go module is released by pushing a semantic version tag:

git tag v0.1.0
git push origin v0.1.0

The GitHub Actions workflow also publishes the browser package to npm when a v* tag is pushed. Before tagging, make sure the npm version matches the tag:

cd packages/browser
npm version 0.1.0 --no-git-tag-version

The publishing job:

npm run build
npm test
npm pack --dry-run
npm publish --access public --provenance

License

This repository is MIT licensed. The bundled Google liblc3 source is Apache-2.0 licensed; see internal/csrc/liblc3/LICENSE.

Documentation

Index

• Constants
• Variables
• type Config
• type Decoder
  • func NewDecoder(cfg Config) (*Decoder, error)
  • func (d *Decoder) Close() error
  • func (d *Decoder) Decode(frame []byte) ([]float32, error)
  • func (d *Decoder) FrameBytes() int
  • func (d *Decoder) FrameSize() int
• type Encoder
  • func NewEncoder(cfg Config) (*Encoder, error)
  • func (e *Encoder) Close() error
  • func (e *Encoder) Encode(samples []float32) ([]byte, error)
  • func (e *Encoder) FrameBytes() int
  • func (e *Encoder) FrameSize() int

Constants

const (
	DefaultSampleRate      = 16000
	DefaultFrameDurationUS = 10000
	DefaultBitrate         = 32000
	MinFrameBytes          = 20
	MaxFrameBytes          = 400
)

Variables

var (
	ErrConfig = errors.New("lc3 config invalid")
	ErrInit   = errors.New("lc3 init failed")
	ErrEncode = errors.New("lc3 encode failed")
	ErrDecode = errors.New("lc3 decode failed")
)

Types

type Config

type Config struct {
	SampleRate      int
	FrameDurationUS int
	Bitrate         int
	FrameBytes      int
}

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

func NewDecoder

func NewDecoder(cfg Config) (*Decoder, error)

func (*Decoder) Close

func (d *Decoder) Close() error

func (*Decoder) Decode

func (d *Decoder) Decode(frame []byte) ([]float32, error)

func (*Decoder) FrameBytes

func (d *Decoder) FrameBytes() int

func (*Decoder) FrameSize

func (d *Decoder) FrameSize() int

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

func NewEncoder

func NewEncoder(cfg Config) (*Encoder, error)

func (*Encoder) Close

func (e *Encoder) Close() error

func (*Encoder) Encode

func (e *Encoder) Encode(samples []float32) ([]byte, error)

func (*Encoder) FrameBytes

func (e *Encoder) FrameBytes() int

func (*Encoder) FrameSize

func (e *Encoder) FrameSize() int