wav

Documentation

Overview

Package wav reads and writes WAV (RIFF/WAVE) file metadata.

Two metadata containers are recognised:

• "LIST" chunks of type "INFO" — the classic RIFF INFO tags (INAM, IART, IPRD, ICRD, IGNR, ICMT, ITRK, …). Values are stored as NUL-terminated strings, conventionally CP1252 / latin-1 but increasingly UTF-8 in modern writers; this package treats them as UTF-8 and round-trips bytes unchanged.

• "id3 " chunks containing an embedded ID3v2 tag (the Adobe / Wavelab convention). The body is parsed via the id3v2 subpackage.

All other top-level chunks ("fmt ", "data", "fact", "JUNK", …) are preserved byte-for-byte. WriteFile rewrites the file from the in-memory chunk list, so any chunk ordering produced by Read is faithfully restored.

64-bit RIFF (RF64 / BW64) is detected and rejected with ErrRF64Unsupported; the spec's 64-bit size table (ds64) is not implemented here.

A *File is not safe for concurrent use.

Index

• Constants
• Variables
• type File
  • func Read(rs io.ReadSeeker) (*File, error)
  • func ReadFile(path string) (*File, error)
  • func (f *File) Album() string
  • func (f *File) AlbumArtist() string
  • func (f *File) Artist() string
  • func (f *File) Comment() string
  • func (f *File) Composer() string
  • func (f *File) DiscNumber() (n, total int)
  • func (f *File) Genre() string
  • func (f *File) InfoValue(id string) string
  • func (f *File) Pictures() []*id3v2.PictureFrame
  • func (f *File) SetInfo(id, value string)
  • func (f *File) Title() string
  • func (f *File) TrackNumber() (n, total int)
  • func (f *File) WriteFile(path string) error
  • func (f *File) Year() int
• type InfoItem

Constants

const (
	ChunkLIST = "LIST"
	ChunkINFO = "INFO"
	ChunkID3  = "id3 " // trailing space is part of the FOURCC
)

Chunk IDs used inside a WAVE file. Exported so callers building files by hand (e.g. tests) can reference them without typos.

const (
	InfoTitle      = "INAM" // Track title
	InfoArtist     = "IART" // Artist
	InfoAlbum      = "IPRD" // Product / album
	InfoDate       = "ICRD" // Creation date — typically YYYY-MM-DD or YYYY
	InfoGenre      = "IGNR" // Genre
	InfoComment    = "ICMT" // Comment
	InfoTrack      = "ITRK" // Track number — non-standard but widespread
	InfoComposer   = "IMUS" // Composer — non-standard but used
	InfoCopyright  = "ICOP" // Copyright
	InfoSoftware   = "ISFT" // Software / encoder name
	InfoEngineer   = "IENG" // Engineer
	InfoTechnician = "ITCH" // Technician
)

Common LIST/INFO sub-chunk FOURCCs. These follow the canonical RIFF INFO names defined by Microsoft and used by most taggers.

Variables

var (
	// ErrNoWAV is returned by Read when the input does not begin
	// with "RIFF" + (any 4 bytes) + "WAVE".
	ErrNoWAV = errors.New("wav: missing RIFF/WAVE marker")

	// ErrRF64Unsupported is returned when the input begins with
	// "RF64" or "BW64" — the 64-bit RIFF variants. These need a
	// "ds64" chunk to recover the true sizes; tunetag does not
	// implement that yet and refuses to guess.
	ErrRF64Unsupported = errors.New("wav: RF64 / BW64 (64-bit RIFF) is not supported")

	// ErrInvalidChunk is returned when a chunk header runs past
	// end-of-stream or declares a negative size.
	ErrInvalidChunk = errors.New("wav: invalid chunk header")
)

Errors returned by this package.

Types

type File

type File struct {
	// Info holds LIST/INFO entries in stream order. Use Info
	// directly to add, mutate, or delete entries; the helpers
	// Title()/SetTitle()/… below are convenience wrappers.
	Info []InfoItem

	// ID3 is the embedded id3 chunk's parsed tag, or nil if the
	// file had no id3 chunk. Mutate Frames directly to edit; pass
	// nil to drop the chunk on the next WriteFile.
	ID3 *id3v2.Tag
	// contains filtered or unexported fields
}

File is the parsed metadata + chunk layout of a WAV file. The audio bytes inside "data" (and every non-metadata chunk) are captured verbatim so they can be re-emitted by WriteFile.

func Read

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

Read parses the metadata region (and remembers the full chunk layout) of a WAV file from rs. Audio chunks are not decoded; their bytes are preserved.

func ReadFile

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

ReadFile is a convenience wrapper around Read.

func (*File) Album

func (f *File) Album() string

Album returns the album: ID3v2 first, else IPRD.

func (*File) AlbumArtist

func (f *File) AlbumArtist() string

AlbumArtist returns the album artist from the ID3v2 tag if present. LIST/INFO has no canonical equivalent.

func (*File) Artist

func (f *File) Artist() string

Artist returns the artist: ID3v2 first, else IART.

func (*File) Comment

func (f *File) Comment() string

Comment returns the comment: ID3v2 first, else ICMT.

func (*File) Composer

func (f *File) Composer() string

Composer returns the composer: ID3v2 first, else IMUS.

func (*File) DiscNumber

func (f *File) DiscNumber() (n, total int)

DiscNumber returns the (number, total) pair from ID3v2 only. LIST/INFO has no widely-used disc-number key.

func (*File) Genre

func (f *File) Genre() string

Genre returns the genre: ID3v2 first, else IGNR.

func (*File) InfoValue

func (f *File) InfoValue(id string) string

InfoValue returns the first LIST/INFO value for id, or "".

func (*File) Pictures

func (f *File) Pictures() []*id3v2.PictureFrame

Pictures returns embedded ID3v2 APIC frames. LIST/INFO chunks cannot carry images.

func (*File) SetInfo

func (f *File) SetInfo(id, value string)

SetInfo sets (or replaces) the first LIST/INFO entry for id. Passing an empty value removes the entry.

func (*File) Title

func (f *File) Title() string

Title returns the most-informative title available: the ID3v2 frame if present, otherwise the LIST/INFO INAM entry.

func (*File) TrackNumber

func (f *File) TrackNumber() (n, total int)

TrackNumber returns the (number, total) pair, preferring ID3v2 over the non-standard ITRK INFO entry.

func (*File) WriteFile

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

WriteFile rewrites path with the current chunk layout. The caller's audio bytes are preserved; only LIST/INFO and id3 chunks are regenerated from f.Info and f.ID3 respectively.

When f.Info is empty the LIST chunk is omitted. When f.ID3 is nil the id3 chunk is omitted. If either is set but no placeholder exists in the original chunk list (e.g. a file that gained tags after Read), the missing chunk is appended at the end so it sits after the audio data, which is the most compatible position for players that pre-buffer "data".

func (*File) Year

func (f *File) Year() int

Year returns the 4-digit year from ID3v2 if present, otherwise the leading 4 digits of ICRD (which may be YYYY or YYYY-MM-DD).

type InfoItem

type InfoItem struct {
	ID    string // exactly 4 ASCII bytes; consumers should use the Info* constants
	Value string
}

InfoItem is one entry inside a LIST/INFO chunk: a 4-character ID (e.g. "INAM") and its NUL-terminated value. Trailing NULs are stripped on Read; the writer re-pads as required.