soundsetgo

package module
v0.0.0-...-98b0e72 Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2026 License: MIT Imports: 10 Imported by: 0

README

soundsetgo

Author: Bodo Hinüber

soundsetgo is a small Go audio conversion library aimed at retro sound formats. It uses pure Go decoders and does not shell out to external players such as sidplayfp, xmp, asap, uade, hivelytracker, or game-music-emu.

Bundled decoders currently render WAV PCM, Amiga IFF 8SVX, Atari ST YM files, PSID/RSID files, and ProTracker-compatible MOD files to signed 16-bit PCM. Native metadata parsers are also registered for XM, S3M, IT, AHX, HVL, SAP, and NSF files. Those parser-only formats return ErrDecoderNotImplemented from RenderPCM until their native emulator or mixer cores are added.

Features

  • Generic decoder registry
  • Usable from normal Go programs, CLIs, servers, desktop apps, and Wails apps
  • WAV decoder for PCM 8-bit and 16-bit files
  • 8SVX decoder for uncompressed and Fibonacci-delta compressed Amiga samples
  • YM2/YM3/YM5/YM6 decoder with a simple AY/YM2149 tone renderer
  • SID/PSID/RSID decoder with native 6502 subroutine execution and basic SID synthesis
  • ProTracker-compatible MOD decoder with a native sample mixer
  • Native metadata parsers for NSF, SAP, XM, S3M, IT, AHX, and HVL
  • Raw signed 16-bit little-endian PCM export
  • WAV export and browser-friendly WAV data URL export
  • Machine-readable format registry metadata

Install / use locally

go test ./...
go run ./cmd/soundsetgo -o mod.okeanos-jesuisk.wav testsounds/mod.okeanos-jesuisk.mod
go run ./cmd/soundsetgo -o einekatze.sid.wav testsounds/einekatze.sid
go run ./cmd/soundsetgo -o output.wav input.ym
go run ./cmd/soundsetgo -duration 120 -o output.wav input.mod
go run ./cmd/soundsetgo -o output.wav input.wav
go run ./cmd/soundsetgo -o output.wav input.8svx
go run ./cmd/soundsetgo -o output.wav input.sid
go run ./cmd/soundsetgo -raw -o output.raw input.ym
go run ./cmd/soundsetgo -info input.sid
go run ./cmd/soundsetgo -formats-json

Library usage

package main

import (
    "os"

    "codeberg.org/rabenauge/soundsetgo"
    _ "codeberg.org/rabenauge/soundsetgo/formats/all"
)

func main() {
    snd, err := soundsetgo.DecodeFile("input.ym")
    if err != nil {
        panic(err)
    }

    wavBytes, err := soundsetgo.EncodeWAV(snd)
    if err != nil {
        panic(err)
    }

    if err := os.WriteFile("output.wav", wavBytes, 0644); err != nil {
        panic(err)
    }
}

Format registry API

Use soundsetgo.RegisteredFormatInfos() to get the currently registered decoders as machine-readable data:

infos := soundsetgo.RegisteredFormatInfos()

The CLI exposes the same data as JSON:

go run ./cmd/soundsetgo -formats-json

Wails-style usage

Bind adapters/wails3.SoundService in your Wails3 app. The service method returns a WAV Data URL that can be assigned to an audio source in the frontend.

src, err := wails3.SoundService{}.LoadSound("input.ym")

Frontend:

audio.src = await SoundService.LoadSound(path)

Adding another format

Create a package that implements soundsetgo.Decoder and registers itself:

package myformat

import "codeberg.org/rabenauge/soundsetgo"

type Decoder struct{}

func init() { soundsetgo.Register(Decoder{}) }
func (Decoder) Format() string { return "myformat" }
func (Decoder) Match(data []byte) bool { return len(data) > 4 /* ... */ }
func (Decoder) Decode(data []byte, opts soundsetgo.Options) (*soundsetgo.Sound, error) {
    /* ... */
}

Then import it for side effects:

import _ "your/module/formats/myformat"

Current decoder limitations

WAV support is limited to uncompressed PCM 8-bit and 16-bit samples. 8SVX support handles mono samples and the common CHAN stereo layout; ATAK/RLSE envelopes are parsed past but not applied. YM support currently renders the three tone channels and does not emulate envelope shape, noise, digidrums, or chip-specific filtering.

The SID decoder supports PSID/RSID loading, 6502 init/play subroutine execution, and direct $D400 SID register synthesis. It intentionally does not yet emulate C64 ROM calls, CIA/VIC timing, illegal opcodes, or the analog SID filter model, so highly timing-sensitive or illegal-opcode tunes may fail explicitly.

The MOD decoder supports ProTracker-style sample playback, loops, stereo panning, speed/BPM changes, and common effects such as arpeggio, slides, vibrato, volume changes, pattern breaks, and position jumps. It does not emulate the Amiga LED filter and does not yet cover every edge-case effect from all MOD variants.

NSF, SAP, XM, S3M, IT, AHX, and HVL parsing is intentionally native but metadata-only for now. Real playback still needs CPU/chip emulators or tracker mixer cores, so these formats fail explicitly during rendering instead of pretending to be complete.

Documentation

Index

Constants

View Source 
const DefaultSampleRate = 44100

Variables

View Source 
var ErrDecoderNotImplemented = errors.New("native decoder not implemented yet")
View Source 
var ErrUnsupportedFormat = errors.New("unsupported format")

Functions

func EncodeDataURL 

func EncodeDataURL(s *Sound) (string, error)

func EncodePCM16LE 

func EncodePCM16LE(s *Sound) ([]byte, error)

func EncodeWAV 

func EncodeWAV(s *Sound) ([]byte, error)

func FileToDataURL 

func FileToDataURL(path string, opts ...Options) (string, error)

func Register 

func Register(d Decoder)

func RegisteredFormats 

func RegisteredFormats() []string

func RenderAll 

func RenderAll(s *Sound) ([]int16, error)

Types

type Decoder 

type Decoder interface {
	Format() string
	Match(data []byte) bool
	Decode(data []byte, opts Options) (*Sound, error)
}

type Format 

type Format string
const (
	FormatWAV  Format = "wav"
	Format8SVX Format = "8svx"
	FormatYM   Format = "ym"
	FormatSID  Format = "sid"
	FormatMOD  Format = "mod"
	FormatXM   Format = "xm"
	FormatS3M  Format = "s3m"
	FormatIT   Format = "it"
	FormatAHX  Format = "ahx"
	FormatHVL  Format = "hvl"
	FormatSAP  Format = "sap"
	FormatNSF  Format = "nsf"
)

func DetectFormat 

func DetectFormat(name string, data []byte) (Format, error)

type FormatDescriber 

type FormatDescriber interface {
	FormatInfo() FormatInfo
}

type FormatInfo 

type FormatInfo struct {
	Format      string   `json:"format"`
	Description string   `json:"description,omitempty"`
	Extensions  []string `json:"extensions,omitempty"`
	MimeTypes   []string `json:"mimeTypes,omitempty"`
	NativePCM   bool     `json:"nativePcm"`
}

func RegisteredFormatInfos 

func RegisteredFormatInfos() []FormatInfo

type Info 

type Info struct {
	Format     Format
	Title      string
	Author     string
	Comment    string
	SampleRate int
	Channels   int
}

type Options 

type Options struct {
	SampleRate      int
	DurationSeconds int
}

type PCMRenderer 

type PCMRenderer interface {
	RenderPCM(dst []int16) (int, error)
}

type Sound 

type Sound struct {
	TrackInfo Info
	Meta      map[string]any
	Renderer  PCMRenderer
}

func Decode 

func Decode(name string, data []byte, opts ...Options) (*Sound, error)

func DecodeData 

func DecodeData(data []byte, opts ...Options) (*Sound, error)

func DecodeFile 

func DecodeFile(path string, opts ...Options) (*Sound, error)

func NewPendingSound 

func NewPendingSound(info Info, meta map[string]any) *Sound

func Open 

func Open(path string, opts ...Options) (*Sound, error)

func (*Sound) Info 

func (s *Sound) Info() Info

func (*Sound) RenderPCM 

func (s *Sound) RenderPCM(dst []int16) (int, error)

Source Files

View all Source files

Directories

Path Synopsis
adapters
wails3
Package wails3 contains a small service type that can be bound in a Wails app.
 Package wails3 contains a small service type that can be bound in a Wails app.
cmd
soundsetgo command
formats
ahx
Package ahx registers a native AHX metadata parser.
 Package ahx registers a native AHX metadata parser.
all
Package all registers all decoders bundled with soundsetgo.
 Package all registers all decoders bundled with soundsetgo.
eightsvx
Package eightsvx registers a decoder for Amiga IFF 8SVX audio.
 Package eightsvx registers a decoder for Amiga IFF 8SVX audio.
hvl
Package hvl registers a native HivelyTracker metadata parser.
 Package hvl registers a native HivelyTracker metadata parser.
internal/meta
it
Package it registers a native Impulse Tracker metadata parser.
 Package it registers a native Impulse Tracker metadata parser.
mod
Package mod registers a native ProTracker MOD decoder.
 Package mod registers a native ProTracker MOD decoder.
nsf
Package nsf registers a native NSF metadata parser.
 Package nsf registers a native NSF metadata parser.
s3m
Package s3m registers a native Scream Tracker 3 metadata parser.
 Package s3m registers a native Scream Tracker 3 metadata parser.
sap
Package sap registers a native SAP metadata parser.
 Package sap registers a native SAP metadata parser.
sid
Package sid registers a native PSID/RSID decoder.
 Package sid registers a native PSID/RSID decoder.
wav
Package wav registers a decoder for PCM WAV audio.
 Package wav registers a decoder for PCM WAV audio.
xm
Package xm registers a native FastTracker XM metadata parser.
 Package xm registers a native FastTracker XM metadata parser.
ym
Package ym registers a decoder for Atari ST YM music dumps.
 Package ym registers a decoder for Atari ST YM music dumps.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.