flac

Documentation

Overview

Package flac reads and writes FLAC metadata blocks. The audio data is preserved untouched; only the metadata region between the "fLaC" marker and the first audio frame is rewritten.

Only VORBIS_COMMENT and PICTURE blocks are typed; the rest (STREAMINFO, SEEKTABLE, CUESHEET, APPLICATION, PADDING, unknown) round-trip as raw bytes via RawBlock so that callers don't need the package to understand every block type to mutate metadata.

A *File is not safe for concurrent use.

Index

• Constants
• Variables
• type Block
• type File
  • func Read(rs io.ReadSeeker) (*File, error)
  • func ReadFile(path string) (*File, error)
  • func (f *File) AddPicture(p *Picture)
  • func (f *File) Pictures() []*Picture
  • func (f *File) RemovePictures()
  • func (f *File) VorbisComment() *VorbisComment
  • func (f *File) WriteFile(path string) error
• type PaddingBlock
  • func (p *PaddingBlock) Encode() ([]byte, error)
  • func (p *PaddingBlock) Type() uint8
• type Picture
  • func ParsePicture(body []byte) (*Picture, error)
  • func (p *Picture) Encode() ([]byte, error)
  • func (p *Picture) Type() uint8
• type RawBlock
  • func (r *RawBlock) Encode() ([]byte, error)
  • func (r *RawBlock) Type() uint8
• type VorbisComment
  • func ParseVorbisComment(body []byte) (*VorbisComment, error)
  • func (vc *VorbisComment) Add(key, value string)
  • func (vc *VorbisComment) Encode() ([]byte, error)
  • func (vc *VorbisComment) First(key string) string
  • func (vc *VorbisComment) Get(key string) []string
  • func (vc *VorbisComment) Remove(key string)
  • func (vc *VorbisComment) Set(key, value string)
  • func (vc *VorbisComment) Type() uint8

Constants

const (
	BlockStreamInfo    uint8 = 0
	BlockPadding       uint8 = 1
	BlockApplication   uint8 = 2
	BlockSeekTable     uint8 = 3
	BlockVorbisComment uint8 = 4
	BlockCueSheet      uint8 = 5
	BlockPicture       uint8 = 6
)

Block types per the FLAC format specification.

const MaxBlockSize = 1<<24 - 1

MaxBlockSize is the maximum payload length of a single FLAC metadata block (24 bits = 16 MiB - 1).

const VendorString = "tunetag"

VendorString is the default vendor comment emitted on encode if the block has no vendor set.

Variables

var ErrNoFLAC = errors.New("flac: missing fLaC marker")

ErrNoFLAC is returned by Read when the input does not begin with the "fLaC" marker.

var Magic = [4]byte{'f', 'L', 'a', 'C'}

Magic is the four-byte stream marker at the start of every FLAC stream.

Types

type Block

type Block interface {
	// Type is the FLAC block-type byte (low 7 bits of the header).
	Type() uint8
	// Encode returns the block payload (header excluded).
	Encode() ([]byte, error)
}

Block is one FLAC metadata block (excluding the 4-byte header). Implementations must round-trip through Encode without loss.

type File

type File struct {
	Blocks []Block
	// contains filtered or unexported fields
}

File is the parsed metadata region of a FLAC file. Blocks holds every metadata block in stream order; Blocks[0] is always STREAMINFO. The audioOffset records where the first audio frame begins in the source file (used by WriteFile only).

func Read

func Read(rs io.ReadSeeker) (*File, error)

Read parses the metadata region of rs. The audio frames are not consumed.

func ReadFile

func ReadFile(path string) (*File, error)

ReadFile is a convenience wrapper around Read.

func (*File) AddPicture

func (f *File) AddPicture(p *Picture)

AddPicture appends a PICTURE block.

func (*File) Pictures

func (f *File) Pictures() []*Picture

Pictures returns every PICTURE block in stream order.

func (*File) RemovePictures

func (f *File) RemovePictures()

RemovePictures deletes every PICTURE block.

func (*File) VorbisComment

func (f *File) VorbisComment() *VorbisComment

VorbisComment returns the first VORBIS_COMMENT block, creating one (and inserting it after STREAMINFO) if absent. The returned block is the one stored inside f, so mutations are persisted across subsequent WriteFile calls.

func (*File) WriteFile

func (f *File) WriteFile(path string) error

WriteFile writes f back to path. When the new non-padding blocks fit within the bytes occupied by the previous metadata region the difference is absorbed by a single trailing PADDING block so the audio bytes stay in place. Otherwise the file is rewritten via a temporary file and atomic rename.

type PaddingBlock

type PaddingBlock struct {
	Size int
}

PaddingBlock is the explicit zero-padding block. Its size is the number of zero bytes to emit, exclusive of the 4-byte header.

func (*PaddingBlock) Encode

func (p *PaddingBlock) Encode() ([]byte, error)

func (*PaddingBlock) Type

func (p *PaddingBlock) Type() uint8

type Picture

type Picture struct {
	PictureType   uint32
	MIME          string
	Description   string
	Width         uint32
	Height        uint32
	Depth         uint32 // bits per pixel
	IndexedColors uint32 // 0 for non-indexed images
	Data          []byte
}

Picture is a FLAC METADATA_BLOCK_PICTURE. The PictureType byte values match the 21 ID3v2 APIC types and the tunetag.PictureType enum, so block contents can be moved between formats losslessly.

func ParsePicture

func ParsePicture(body []byte) (*Picture, error)

ParsePicture decodes a FLAC METADATA_BLOCK_PICTURE body into a *Picture. Exposed for callers outside FLAC (notably the ogg package, where Vorbis Comment's METADATA_BLOCK_PICTURE entries contain the same byte layout, base64-encoded).

func (*Picture) Encode

func (p *Picture) Encode() ([]byte, error)

func (*Picture) Type

func (p *Picture) Type() uint8

type RawBlock

type RawBlock struct {
	BlockType uint8
	Body      []byte
}

RawBlock preserves the original bytes of a block whose payload this package does not parse (STREAMINFO, SEEKTABLE, CUESHEET, APPLICATION, unknown types). Re-emitting RawBlock is byte-perfect.

func (*RawBlock) Encode

func (r *RawBlock) Encode() ([]byte, error)

func (*RawBlock) Type

func (r *RawBlock) Type() uint8

type VorbisComment

type VorbisComment struct {
	Vendor   string
	Comments []string
}

VorbisComment is a FLAC METADATA_BLOCK_VORBIS_COMMENT. Comments are stored as raw "KEY=value" UTF-8 strings preserving the original case of KEY, but lookups via Get / Set / Remove use case-insensitive comparison per the Vorbis Comment specification.

All multi-byte integers in the on-disk representation are little-endian, in contrast to the rest of the FLAC stream which is big-endian.

func ParseVorbisComment

func ParseVorbisComment(body []byte) (*VorbisComment, error)

ParseVorbisComment decodes a Vorbis Comment block body (vendor length + vendor + comment count + length-prefixed "KEY=value" entries) into a VorbisComment. The on-disk format is identical to the one used by Ogg Vorbis and Ogg Opus comment packets, so callers outside FLAC can reuse this parser by passing the body after stripping any codec-specific magic prefix (and Vorbis's trailing framing bit, if present).

func (*VorbisComment) Add

func (vc *VorbisComment) Add(key, value string)

Add appends a value without removing any existing entries.

func (*VorbisComment) Encode

func (vc *VorbisComment) Encode() ([]byte, error)

func (*VorbisComment) First

func (vc *VorbisComment) First(key string) string

First is a convenience: returns the first value for key or "".

func (*VorbisComment) Get

func (vc *VorbisComment) Get(key string) []string

Get returns every value for the given key, case-insensitively.

func (*VorbisComment) Remove

func (vc *VorbisComment) Remove(key string)

Remove deletes every entry whose key matches case-insensitively.

func (*VorbisComment) Set

func (vc *VorbisComment) Set(key, value string)

Set replaces every existing entry for key with a single value. An empty value removes all entries for the key.

func (*VorbisComment) Type

func (vc *VorbisComment) Type() uint8