flac

README

flac

This package provides access to FLAC (Free Lossless Audio Codec) streams.

Documentation

Documentation provided by GoDoc.

• flac: provides access to FLAC (Free Lossless Audio Codec) streams.
  • frame: implements access to FLAC audio frames.
  • meta: implements access to FLAC metadata blocks.

Changes

• Version 1.0.7 (2021-01-28)

  • Add seek API (see #44 and #46). Thanks to Craig Swank.

• Version 1.0.6 (2019-12-20)

  • Add experimental Encoder API to encode audio samples and metadata blocks (see #32).
  • Use go.mod.
  • Skip ID3v2 data prepended to flac files when parsing (see 36cc17e).
    • Remove dependency on encodebytes. Thanks to Mikey Dickerson.
  • Add 16kHz test case. Thanks to Chewxy.
  • Fix lint issues (see #25).

• Version 1.0.5 (2016-05-06)

  • Simplify import paths. Drop use of gopkg.in, and rely on vendoring instead (see azul3d/engine#1).
  • Add FLAC decoding benchmark (see d675e0a)

• Version 1.0.4 (2016-02-11)

  • Add API examples to documentation (see #11).
  • Extend test cases (see aadf80a).

• Version 1.0.3 (2016-02-02)

  • Implement decoding of FLAC files with wasted bits-per-sample (see #12).
  • Stress test the library using go-fuzz (see #10). Thanks to Patrick Mézard.

• Version 1.0.2 (2015-06-05)

  • Fix decoding of blocking strategy (see #9). Thanks to Sergey Didyk.

• Version 1.0.1 (2015-02-25)

  • Fix two subframe decoding bugs (see #7). Thanks to Jonathan MacMillan.
  • Add frame decoding test cases.

• Version 1.0.0 (2014-09-30)

  • Initial release.
  • Implement decoding of FLAC files.

Documentation

Overview

Package flac provides access to FLAC (Free Lossless Audio Codec) streams.

A brief introduction of the FLAC stream format [1] follows. Each FLAC stream starts with a 32-bit signature ("fLaC"), followed by one or more metadata blocks, and then one or more audio frames. The first metadata block (StreamInfo) describes the basic properties of the audio stream and it is the only mandatory metadata block. Subsequent metadata blocks may appear in an arbitrary order.

Please refer to the documentation of the meta [2] and the frame [3] packages for a brief introduction of their respective formats.

[1]: https://www.xiph.org/flac/format.html#stream
[2]: https://godoc.org/github.com/apatterson-cogo/flac/meta
[3]: https://godoc.org/github.com/apatterson-cogo/flac/frame

Note: the Encoder API is experimental until the 1.1.x release. As such, it's API is expected to change.

Index

• Variables
• type Encoder
  • func NewEncoder(w io.Writer, info *meta.StreamInfo, blocks ...*meta.Block) (*Encoder, error)
  • func (enc *Encoder) Close() error
  • func (enc *Encoder) WriteFrame(f *frame.Frame) error
• type Stream
  • func New(r io.Reader) (stream *Stream, err error)
  • func NewSeek(rs io.ReadSeeker) (stream *Stream, err error)
  • func Open(path string) (stream *Stream, err error)
  • func Parse(r io.Reader) (stream *Stream, err error)
  • func ParseFile(path string) (stream *Stream, err error)
  • func (stream *Stream) Close() error
  • func (stream *Stream) Next() (f *frame.Frame, err error)
  • func (stream *Stream) ParseNext() (f *frame.Frame, err error)
  • func (stream *Stream) Seek(sampleNum uint64) (uint64, error)

Examples

• Open
• ParseFile

Variables

var (

	// ErrNoSeeker reports that flac.NewSeek was called with an io.Reader not
	// implementing io.Seeker, and thus does not allow for seeking.
	ErrNoSeeker = errors.New("stream.Seek: reader does not implement io.Seeker")

	// ErrNoSeektable reports that no seektable has been generated. Therefore,
	// it is not possible to seek in the stream.
	ErrNoSeektable = errors.New("stream.searchFromStart: no seektable exists")
)

Types

type Encoder

type Encoder struct {
	// FLAC stream of encoder.
	*Stream
	// contains filtered or unexported fields
}

An Encoder represents a FLAC encoder.

func NewEncoder

func NewEncoder(w io.Writer, info *meta.StreamInfo, blocks ...*meta.Block) (*Encoder, error)

NewEncoder returns a new FLAC encoder for the given metadata StreamInfo block and optional metadata blocks.

func (*Encoder) Close

func (enc *Encoder) Close() error

Close closes the underlying io.Writer of the encoder and flushes any pending writes. If the io.Writer implements io.Seeker, the encoder will update the StreamInfo metadata block with the MD5 checksum of the unencoded audio samples, the number of samples, and the minimum and maximum frame size and block size.

func (*Encoder) WriteFrame

func (enc *Encoder) WriteFrame(f *frame.Frame) error

WriteFrame encodes the given audio frame to the output stream. The Num field of the frame header is automatically calculated by the encoder.

type Stream

type Stream struct {
	// The StreamInfo metadata block describes the basic properties of the FLAC
	// audio stream.
	Info *meta.StreamInfo
	// Zero or more metadata blocks.
	Blocks []*meta.Block
	// contains filtered or unexported fields
}

A Stream contains the metadata blocks and provides access to the audio frames of a FLAC stream.

ref: https://www.xiph.org/flac/format.html#stream

func New

func New(r io.Reader) (stream *Stream, err error)

New creates a new Stream for accessing the audio samples of r. It reads and parses the FLAC signature and the StreamInfo metadata block, but skips all other metadata blocks.

Call Stream.Next to parse the frame header of the next audio frame, and call Stream.ParseNext to parse the entire next frame including audio samples.

func NewSeek

func NewSeek(rs io.ReadSeeker) (stream *Stream, err error)

NewSeek returns a Stream that has seeking enabled. The incoming io.ReadSeeker will not be buffered, which might result in performance issues. Using an in-memory buffer like *bytes.Reader should work well.

func Open

func Open(path string) (stream *Stream, err error)

Open creates a new Stream for accessing the audio samples of path. It reads and parses the FLAC signature and the StreamInfo metadata block, but skips all other metadata blocks.

Call Stream.Next to parse the frame header of the next audio frame, and call Stream.ParseNext to parse the entire next frame including audio samples.

Note: The Close method of the stream must be called when finished using it.

Example

package main

import (
	"bytes"
	"crypto/md5"
	"fmt"
	"io"
	"log"

	"github.com/apatterson-cogo/flac"
)

func main() {
	// Open love.flac for audio streaming without parsing metadata.
	stream, err := flac.Open("testdata/love.flac")
	if err != nil {
		log.Fatal(err)
	}
	defer stream.Close()

	// Parse audio samples and verify the MD5 signature of the decoded audio
	// samples.
	md5sum := md5.New()
	for {
		// Parse one frame of audio samples at the time, each frame containing one
		// subframe per audio channel.
		frame, err := stream.ParseNext()
		if err != nil {
			if err == io.EOF {
				break
			}
			log.Fatal(err)
		}
		frame.Hash(md5sum)

		// Print first three samples from each channel of the first five frames.
		if frame.Num < 5 {
			fmt.Printf("frame %d\n", frame.Num)
			for i, subframe := range frame.Subframes {
				fmt.Printf("  subframe %d\n", i)
				for j, sample := range subframe.Samples {
					if j >= 3 {
						break
					}
					fmt.Printf("    sample %d: %v\n", j, sample)
				}
			}
		}
	}
	fmt.Println()

	got, want := md5sum.Sum(nil), stream.Info.MD5sum[:]
	fmt.Println("decoded audio md5sum valid:", bytes.Equal(got, want))
}

Output:

frame 0
  subframe 0
    sample 0: 126
    sample 1: 126
    sample 2: 126
  subframe 1
    sample 0: 126
    sample 1: 126
    sample 2: 126
frame 1
  subframe 0
    sample 0: 126
    sample 1: 126
    sample 2: 126
  subframe 1
    sample 0: 126
    sample 1: 126
    sample 2: 126
frame 2
  subframe 0
    sample 0: 121
    sample 1: 130
    sample 2: 137
  subframe 1
    sample 0: 121
    sample 1: 130
    sample 2: 137
frame 3
  subframe 0
    sample 0: -9501
    sample 1: -6912
    sample 2: -3916
  subframe 1
    sample 0: -9501
    sample 1: -6912
    sample 2: -3916
frame 4
  subframe 0
    sample 0: 513
    sample 1: 206
    sample 2: 152
  subframe 1
    sample 0: 513
    sample 1: 206
    sample 2: 152

decoded audio md5sum valid: true

func Parse

func Parse(r io.Reader) (stream *Stream, err error)

Parse creates a new Stream for accessing the metadata blocks and audio samples of r. It reads and parses the FLAC signature and all metadata blocks.

Call Stream.Next to parse the frame header of the next audio frame, and call Stream.ParseNext to parse the entire next frame including audio samples.

func ParseFile

func ParseFile(path string) (stream *Stream, err error)

ParseFile creates a new Stream for accessing the metadata blocks and audio samples of path. It reads and parses the FLAC signature and all metadata blocks.

Call Stream.Next to parse the frame header of the next audio frame, and call Stream.ParseNext to parse the entire next frame including audio samples.

Note: The Close method of the stream must be called when finished using it.

Example

package main

import (
	"fmt"
	"log"

	"github.com/apatterson-cogo/flac"
)

func main() {
	// Parse metadata of love.flac
	stream, err := flac.ParseFile("testdata/love.flac")
	if err != nil {
		log.Fatal(err)
	}
	defer stream.Close()

	fmt.Printf("unencoded audio md5sum: %032x\n", stream.Info.MD5sum[:])
	for i, block := range stream.Blocks {
		fmt.Printf("block %d: %v\n", i, block.Type)
	}
}

Output:

unencoded audio md5sum: bdf6f7d31f77cb696a02b2192d192a89
block 0: seek table
block 1: vorbis comment
block 2: padding

func (*Stream) Close

func (stream *Stream) Close() error

Close closes the stream if opened through a call to Open or ParseFile, and performs no operation otherwise.

func (*Stream) Next

func (stream *Stream) Next() (f *frame.Frame, err error)

Next parses the frame header of the next audio frame. It returns io.EOF to signal a graceful end of FLAC stream.

Call Frame.Parse to parse the audio samples of its subframes.

func (*Stream) ParseNext

func (stream *Stream) ParseNext() (f *frame.Frame, err error)

ParseNext parses the entire next frame including audio samples. It returns io.EOF to signal a graceful end of FLAC stream.

func (*Stream) Seek

func (stream *Stream) Seek(sampleNum uint64) (uint64, error)

Seek seeks to the frame containing the given absolute sample number. The return value specifies the first sample number of the frame containing sampleNum.