wittycd

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

README

WittyCD

Plays images of audio CDs in WittyMediaServer the way a CD player does: one continuous program, with no gap between tracks. You need it if you keep CD images in a music or disc library.

An audio CD image playing on the CD screen

A CD image authored for testing from Jazz Sampler, Kevin MacLeod, CC BY 3.0.

What it does

  • Reads images: .cue with .bin, .wav, .aiff or a single .flac; .toc; .ccd with .img; .nrg; .chd; and a bare .iso, .img or .bin that is really audio.
  • Knows the layout: tracks, indexes, pregaps, sessions, data tracks, pre-emphasis flags, ISRCs, the barcode, CD-TEXT and CD+G.
  • Plays without gaps. A disc is one stream, and track changes are places in it. Chosen tracks and repeats play the same way.
  • Streams FLAC or WAV. WAV takes no encoding. FLAC uses its own small encoder.
  • Corrects pre-emphasis on flagged tracks, and gives the same samples when you seek as when you play through.
  • Gets album details. MusicBrainz and the Cover Art Archive are asked only by the disc's table of contents. Finding names online, and how a library shows a disc, stay with the server.
  • Reports problems. An image whose audio is scrambled shows up as noise and is reported, and so is a DTS surround disc. Nothing is decrypted or bypassed.

It doesn't read these:

  • Compressed audio other than a single FLAC (.mp3, .ape and so on). A sheet beside per-track FLAC files isn't treated as an image either, since those are tagged songs already.
  • Raw .sub files for CD+G. Use a .cdg file beside the image.
  • CD-TEXT in double-byte character sets, which is reported instead.

CCD and NRG are tested against images built to their published descriptions, not against dumps from the original programs. CHD and TOC are checked against the real tools.

How to use it is in Help inside WittyMediaServer: see Music, audiobooks and podcasts.

How to get it

An admin adds it from the module store inside WittyMediaServer: Settings → Modules, then Browse the store, then Add beside WittyCD. That needs WittyMediaServer 0.6.0-alpha or later, and it works with nothing older. The range this version fits is in module.json: 0.6.0-alpha through 0.6.x.

What it needs

  • WittyModule, which is how a server talks to it, built in. Nothing else.
  • No music comes with it.

It's written in Go with no cgo, from the publicly described formats.

Platforms

A program is built for each system below, and the server uses the right one.

System Where it stands
Linux (x64, arm64, 32-bit ARM, x86) Its tests pass on x64. The other CPUs are only built
Windows (x64, arm64) Built. This version hasn't been run on Windows since it became its own program
macOS (Intel, Apple silicon) Built by the release tool. It has not been run on a real Mac
FreeBSD (amd64, arm64) Cross-compiled only. It has not been run

On macOS and FreeBSD the server has no sandbox for a module's helper: it gets a small environment and a soft memory limit, and nothing more.

Building and testing

You need Go 1.26 or newer. In a worktree, first run the copy of dev-modules.mjs kept above the repositories (node D:/projects/dev-modules.mjs on the development machine). It writes a go.work that git ignores, so the checkout builds against the repositories beside it. Never run go work use.

go vet ./...
go test ./... -count=1
go run github.com/wittywilla/wittymodule/cmd/wittymodule check .

The last one checks the manifest. On the same tool, pack -targets linux/amd64 -out release . builds a release for one system. CI also builds for every system.

To look at an image by hand:

go run ./cmd/wittycd info "Album.cue"
go run ./cmd/wittycd check "Album.cue"

info shows the structure. check reads the whole image and says what's wrong.

To use it as a library, wittycd.Open gives a Disc. NewStream, TrackStream and RangeStream give a stream readable at any offset by any number of readers, with WriteFLAC and WAV. TOC gives MusicBrainzID, LookupString and CDDBID. The lookup package asks MusicBrainz and the Cover Art Archive, and has an Attribution to show wherever the data is used.

Licence

GNU Affero General Public License v3.0 (or later): see LICENSE and NOTICE. If you redistribute it or build on it, please keep the NOTICE attribution. It contains no code from GPL libraries. Disc IDs follow the method published by MusicBrainz, which isn't connected with this project. Each release archive carries a THIRD-PARTY-NOTICES.txt for what its programs link.

WittyCD is an independent open-source project. It isn't associated with, sponsored by or endorsed by the owners of the Compact Disc format, any record label or artist, or MusicBrainz. It isn't a licensed Compact Disc product and uses no disc logo. It reads CD images you already have: no music comes with it, and you're responsible for having the rights to what you open. Album details come from the MusicBrainz and Cover Art Archive services, which are asked only by a disc's table of contents. Any third-party names here only describe what it works with, and belong to their owners. It's provided “as is”, with no warranty; see LICENSE. Local law applies to how you use it. This isn't legal advice.

Releasing

A version tag builds a program for every platform, signs the checksum list, and publishes a release that servers can install.

Versions move in small steps as work lands. go run github.com/wittywilla/wittymodule/cmd/wittymodule@v0.4.0 bump . raises it everywhere it is written (add -part minor for a bigger step). A bump isn't a release: nothing is tagged or published until you tag it. CI fails when code changed since the last tag and the version didn't, because tags never move.

To release:

  1. Check that version in module.json is the one to publish, with the bump committed.
  2. Tag that commit and push the tag: git tag vX.Y.Z, then git push origin vX.Y.Z. A tag with a suffix, such as v1.2.0-beta, is published as a prerelease.
  3. Watch the Actions tab. The signing step uses the WMS_SIGNING_KEY secret of the release environment, and nothing is published without it.

To take a version back, run the withdraw workflow from the Actions tab. It adds the version to a signed list on the release tagged withdrawals, which servers read.

Licensed under AGPL-3.0-or-later: see LICENSE and NOTICE.

Documentation

Overview

Package wittycd reads images of audio CDs and plays them the way a CD player does: one continuous program area, with tracks, indexes and pregaps as places in it rather than as separate files. That is what makes it gapless, and what lets a position be a sample rather than an estimate.

Everything in an image is untrusted: sizes are checked before use, a sheet can only name files beside itself, and a damaged image gives a smaller disc or a clear error, never a crash.

Index

Constants

View Source
const (
	// SectorBytes is one sector of CD audio: 1/75 of a second.
	SectorBytes = 2352
	// SectorSamples is the stereo samples in a sector.
	SectorSamples = 588
	// SampleBytes is one stereo sample: two 16-bit values.
	SampleBytes = 4
	// SampleRate is what every audio CD plays at.
	SampleRate = 44100
	// FramesPerSecond is sectors per second, the F of MM:SS:FF.
	FramesPerSecond = 75
	// LeadIn is the 2 seconds before LBA 0, in sectors: MM:SS:FF counts them on a
	// real disc, and disc IDs add them to every offset.
	LeadIn = 150

	// MaxSectors is the longest disc there can be: 99:59:74.
	MaxSectors = 450000
	// MaxTracks is the most a disc's table of contents can hold.
	MaxTracks = 99
)
View Source
const HiddenTrackNumber = 0

HiddenTrackNumber asks a Stream for what is in track 1's pregap.

View Source
const MaxLoops = 64

MaxLoops bounds how many times a program can be repeated in one stream.

View Source
const ModuleID = "wittycd"

ModuleID is this module's ID, the same as module.json's.

Variables

View Source
var (
	// ErrNotCD: not a CD image at all, such as a DVD or a data disc's ISO.
	ErrNotCD = errors.New("this isn't an image of an audio CD")
	// ErrNoAudio: a CD image with only data tracks.
	ErrNoAudio = errors.New("this CD image holds only data tracks, so there is nothing to play")
	// ErrUnsupported: a CD image in a form this version can't read.
	ErrUnsupported = errors.New("this CD image is stored in a form WittyCD can't read")
)

Errors a caller may want to tell apart. Each reads as a sentence.

View Source
var ForeignAudio func(path string) (flac string, err error)

ForeignAudio, when set, gives a FLAC file of CD audio for a sound file in a format this package doesn't read itself, so that a cue sheet can split it into tracks. It may take a while the first time. The server sets it, since it has FFmpeg and a cache.

View Source
var ManifestJSON []byte

ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").

Functions

func IsImageName

func IsImageName(name string) bool

IsImageName says whether a file's name marks it as a CD image's sheet or container. .iso, .img and .bin may be one too, which only opening them tells.

func MayBeRaw

func MayBeRaw(name string) bool

MayBeRaw says whether a file with this name might be bare CD audio.

func SheetFiles

func SheetFiles(path string) (files []string, image bool)

SheetFiles lists the files a sheet plays, resolved beside it, without opening any of them, and says whether the sheet is really a disc image. It is cheap enough for a scan to ask about every sheet it finds.

A sheet is not treated as an image when its audio is already a set of separately compressed files, one to a track: those are tagged songs, and the sheet is just a rip's notes. The same goes for a sheet naming compressed audio WittyCD can't read. A .ccd, .nrg or .chd holds its own audio, and is always an image.

func UI added in v0.2.1

func UI() *sdui.Module

UI is WittyCD's part of every app (module API 4, WittyMediaServer docs/SDUI-MODULES.md), written to sdui.json beside module.json. It is only the theme scope, on purpose:

  • An audio CD's page and its tracks are the server's music pages, drawn from what this module's helper reads, so a page or menu entry here would only show them twice.
  • The helper reads no settings of its own, and answers no data source: a CD image is an item of the server's music libraries already.

The scope still names the module for the theme editor.

Types

type Disc

type Disc struct {
	Path string `json:"-"`
	// Format is the image's form: cue, toc, ccd, nrg, chd or raw.
	Format  string  `json:"format"`
	Tracks  []Track `json:"tracks"`
	Text    Text    `json:"text"`
	Catalog string  `json:"catalog,omitempty"` // the disc's barcode, if it says
	Genre   string  `json:"genre,omitempty"`
	Date    string  `json:"date,omitempty"`
	// DiscNumber is from the sheet (REM DISCNUMBER), 0 when it doesn't say.
	DiscNumber int `json:"discNumber,omitempty"`
	// Sessions is 2 for a CD-Extra.
	Sessions int `json:"sessions"`
	// HiddenTrack: track 1's pregap holds audio that is not silence.
	HiddenTrack bool `json:"hiddenTrack,omitempty"`
	// Problem is why this disc would not sound like music: "dts" or "noise" with
	// a plain Warning alongside it, "" for a normal disc.
	Problem  string    `json:"problem,omitempty"`
	Warnings []Warning `json:"warnings,omitempty"`
	// HasGraphics: the image holds CD+G subcode (a karaoke disc).
	HasGraphics bool `json:"hasGraphics,omitempty"`
	// contains filtered or unexported fields
}

Disc is an opened CD image.

func Open

func Open(path string) (*Disc, error)

Open reads a CD image by what its name says it is. An .img opens through the .ccd or .cue beside it when there is one.

func (*Disc) AudioEnd

func (d *Disc) AudioEnd() int

AudioEnd is the sector after the last audio track.

func (*Disc) AudioTracks

func (d *Disc) AudioTracks() []*Track

AudioTracks lists the tracks that can be played, in order.

func (*Disc) Check

func (d *Disc) Check(progress func(done float64) bool) *Report

Check reads every audio sector of the disc and reports what it finds. progress, if given, is called now and then with the fraction done and can stop the check by returning false. It is the hook for the Disk Diagnoser and for `cd check`.

func (*Disc) Close

func (d *Disc) Close() error

Close lets go of the image's files.

func (*Disc) DurationSec

func (d *Disc) DurationSec() float64

DurationSec is the disc's playing time, from track 1's index 1 to the last track's end. A hidden track is left out, as a player would.

func (*Disc) Facts

func (d *Disc) Facts() Facts

Facts reads a disc's structure.

func (*Disc) IsSilentRange

func (d *Disc) IsSilentRange(from, to int) bool

IsSilentRange reports whether a run of sectors is digital silence. The player uses it to tell a real pause from an empty pregap.

func (*Disc) NewStream

func (d *Disc) NewStream(tracks []int, loops int, deemphasis bool) (*Stream, error)

NewStream makes a program. tracks is nil for the whole disc as laid out, with every pregap in place (the disc starts at sample 0, which is track 1's pregap when it has one). Pre-emphasised tracks are corrected when deemphasis is on, so they sound as they were meant to.

func (*Disc) RangeStream

func (d *Disc) RangeStream(from, to int) (*Stream, error)

RangeStream is any run of audio sectors exactly as it is on the disc, for a rip that keeps pregaps its own way. Sectors of a data track, or that the image doesn't supply, read as silence.

func (*Disc) ReadGraphics

func (d *Disc) ReadGraphics(from, sectors int) ([]byte, error)

ReadGraphics returns the CD+G packets of a run of sectors, each packet's bytes masked to the 6 bits that carry graphics. Sectors with no graphics read as zeroes, which a decoder ignores.

func (*Disc) TOC

func (d *Disc) TOC() TOC

TOC works out the table of contents an audio player would read. Data tracks aren't counted. On a CD-Extra the lead-out is where the audio session ended, 11400 sectors before the data session if the image kept that gap.

func (*Disc) TotalBytes

func (d *Disc) TotalBytes() int64

TotalBytes is the size of the files the image is made of.

func (*Disc) Track

func (d *Disc) Track(n int) *Track

Track finds a track by number.

func (*Disc) TrackStream

func (d *Disc) TrackStream(n int) (*Stream, error)

TrackStream is one track exactly as it is on the disc, index 1 to its end, with nothing corrected: what a rip wants.

type Facts

type Facts struct {
	Format      string    `json:"format"`
	DiscID      string    `json:"discId"`
	CDDBID      string    `json:"cddbId"`
	TOC         string    `json:"toc"`
	Tracks      []Track   `json:"tracks"`
	Sessions    int       `json:"sessions"`
	DurationSec float64   `json:"durationSec"`
	HiddenTrack bool      `json:"hiddenTrack"`
	HasGraphics bool      `json:"hasGraphics"`
	Problem     string    `json:"problem,omitempty"`
	Warnings    []Warning `json:"warnings"`
}

Facts is a disc's structure in plain data.

type Finding

type Finding struct {
	Severity Severity `json:"severity"`
	Code     string   `json:"code"`
	Text     string   `json:"text"`
	// Track is the track concerned, 0 for the whole disc.
	Track int `json:"track,omitempty"`
}

Finding is one thing a check found.

type Index

type Index struct {
	Number int `json:"number"`
	LBA    int `json:"lba"`
}

Index is an index point inside a track.

type Report

type Report struct {
	Facts       Facts     `json:"facts"`
	AudioTracks int       `json:"audioTracks"`
	Sectors     int       `json:"sectors"`
	Unreadable  int       `json:"unreadable"`
	Findings    []Finding `json:"findings"`
	Worst       Severity  `json:"worst"`
	Summary     string    `json:"summary"`
}

Report is the outcome of reading a whole disc.

type Severity

type Severity string

Severity is how much a finding matters.

const (
	SeverityOK      Severity = "ok"
	SeverityNote    Severity = "note"
	SeverityProblem Severity = "problem"
)

type Stream

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

Stream reads samples of a program. It is safe for concurrent reads and holds no position, so one Disc can serve any number of listeners.

func (*Stream) ReadAt

func (s *Stream) ReadAt(p []byte, off int64) (int, error)

ReadAt reads little-endian PCM. It returns io.EOF only at the end of the program, and any range is allowed, as HTTP range requests are.

func (*Stream) Reader

func (s *Stream) Reader() io.Reader

Reader reads the whole program in order, as little-endian samples.

func (*Stream) Samples

func (s *Stream) Samples() int64

Samples is the program's length.

func (*Stream) Size

func (s *Stream) Size() int64

Size is the program's length in bytes of little-endian PCM.

func (*Stream) WAV

func (s *Stream) WAV(startSample int64) *WAV

WAV makes a file of the program from a sample onwards.

func (*Stream) WriteFLAC

func (s *Stream) WriteFLAC(w io.Writer, startSample int64) error

WriteFLAC writes the program from a sample onwards as a FLAC stream. It stops at the first write error, which is how a listener leaving ends it.

type TOC

type TOC struct {
	First, Last int
	LeadOut     int
	Offsets     []int // of tracks First to Last
}

TOC is a table of contents as disc ID services take it: audio tracks only, with the 2-second lead-in added to every offset.

func (TOC) CDDBID

func (t TOC) CDDBID() string

CDDBID is the older eight-digit disc ID. It is only shown, for matching a disc against other tools' logs; nothing here looks it up.

func (TOC) LookupString

func (t TOC) LookupString() string

LookupString is the toc= value of a MusicBrainz lookup, which also finds a disc nobody has attached that exact ID to. A release is looked up by its track count from 1, so a first track above 1 (a data track first) is told as it is.

func (TOC) MusicBrainzID

func (t TOC) MusicBrainzID() string

MusicBrainzID is the disc's ID in MusicBrainz: 28 characters, from the SHA-1 of the table of contents written in hexadecimal.

type Text

type Text struct {
	Title      string `json:"title,omitempty"`
	Performer  string `json:"performer,omitempty"`
	Songwriter string `json:"songwriter,omitempty"`
	Composer   string `json:"composer,omitempty"`
	Arranger   string `json:"arranger,omitempty"`
	Message    string `json:"message,omitempty"`
}

Text is what a disc says about itself or about one track.

type Track

type Track struct {
	Number int `json:"number"`
	// Audio is false for a data track, which is listed and never played.
	Audio bool   `json:"audio"`
	Mode  string `json:"mode"` // AUDIO, MODE1/2352 and so on
	// Pregap is where index 0 starts, Start where index 1 starts and End where
	// the next track's pregap starts, all in sectors from LBA 0.
	Pregap int `json:"pregap"`
	Start  int `json:"start"`
	End    int `json:"end"`
	// Indexes above 1.
	Indexes     []Index `json:"indexes,omitempty"`
	PreEmphasis bool    `json:"preEmphasis,omitempty"`
	CopyAllowed bool    `json:"copyAllowed,omitempty"`
	FourChannel bool    `json:"fourChannel,omitempty"`
	ISRC        string  `json:"isrc,omitempty"`
	Session     int     `json:"session,omitempty"`
	Text        Text    `json:"text"`
}

Track is one track of the table of contents, data tracks included.

func (*Track) Sectors

func (t *Track) Sectors() int

Sectors is the track's length from index 1 to its end.

type WAV

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

WAV is a program as a WAV file: a header and then its samples, readable at any offset, with no work for the server beyond reading the image.

func (*WAV) ReadAt

func (w *WAV) ReadAt(p []byte, off int64) (int, error)

ReadAt reads the file.

func (*WAV) Size

func (w *WAV) Size() int64

Size is the whole file's size.

type Warning

type Warning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

Warning is something worth telling the owner about an image that still plays.

Directories

Path Synopsis
Package cli is the command line of the standalone wittycd tool.
Package cli is the command line of the standalone wittycd tool.
cmd
wittycd command
Command wittycd inspects audio CD images with the WittyCD engine: tracks, indexes, CD-TEXT, disc IDs, and a read of the whole image to find damage.
Command wittycd inspects audio CD images with the WittyCD engine: tracks, indexes, CD-TEXT, disc IDs, and a read of the whole image to find damage.
wittycd-module command
Command wittycd-module is WittyCD as a helper process: the only way a server reaches it.
Command wittycd-module is WittyCD as a helper process: the only way a server reaches it.
Package lookup finds out what an audio CD is, from MusicBrainz and the Cover Art Archive, using nothing but its table of contents: no names, no audio, and nothing about the person or their files.
Package lookup finds out what an audio CD is, from MusicBrainz and the Cover Art Archive, using nothing but its table of contents: no names, no audio, and nothing about the person or their files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL