日本語English

Public API Reference

The public functions and methods you call to use go-fmml from your application.

For typical BGM playback you only ever need three groups: ① File loading → ② create an engine with fmcore.NewEngine → ③ Playback control. The ④ FM/PCM core low-level API is for triggering single notes directly without MML, or for building your own sequencer.

① File loading package fileio

fileio.LoadFMVoiceFile(path string) error

FM voice

Reads and parses the FM voice parameter YAML file at the given absolute path and registers it in memory. Minor parse issues are logged as warnings and parsing continues; an error is returned only for a fatal error (e.g. the YAML itself being invalid).

fileio.LoadFMVoiceFileFS(fsys embed.FS, path string) error

FM voice / embed

The embed.FS counterpart of LoadFMVoiceFile, for reading FM voice files embedded into the game binary via go:embed.

fileio.LoadPCMVoiceFile(path string) error

PCM voice

Reads the PCM voice parameter YAML file at the given absolute path, and also loads every WAV file its settings reference, registering the result in memory. If a voiceSetting's fileName is a bare file name with no path, it is resolved relative to the YAML file's own directory. Returns an error if any referenced WAV file fails to load, too.

fileio.LoadPCMVoiceFileFS(fsys embed.FS, path string) error

PCM voice / embed

The embed.FS counterpart of LoadPCMVoiceFile. fileName paths are resolved relative to fsys's own root.

fileio.LoadMMLFile(path string) error

MML

Reads and parses the .mml sequence file at the given absolute path and registers it in memory under its [global] sequenceID.

fileio.LoadMMLFileFS(fsys embed.FS, path string) error

MML / embed

The embed.FS counterpart of LoadMMLFile.

fileio.SetMMLTextData(data string) error

MML / string

Loads MML data supplied directly as a Go string (e.g. a backtick-quoted multi-line literal) instead of from a file (Phase 7). Processing afterward is identical to LoadMMLFile.

fileio.SetFMVoiceData(data string) error

FM voice / string

Loads FM voice parameter data in the same YAML format, supplied directly as a Go string (Phase 7).

fileio.SetPCMVoiceData(data string) error

PCM voice / string

Loads PCM voice parameter data in the same YAML format, supplied directly as a Go string (Phase 7). Relative paths for referenced WAV files are resolved against the process's current working directory.

WAV loading efficiency (Phase 7): LoadPCMVoiceFile / LoadPCMVoiceFileFS / SetPCMVoiceData all reuse an already-cached WAV file (by resolved path) instead of decoding it again.

② Memory management package memory

memory.ClearVoices()

FM voice

Removes every registered FM voice from memory.

memory.ClearPCMVoices()

PCM voice

Removes every registered PCM voice from memory (the decoded waveform cache itself is untouched).

memory.ClearPCMWaveCache()

PCM waveform / Phase 7

Clears the entire cache of decoded WAV waveforms, freeing that memory. This is separate from ClearPCMVoices, which clears voice (音色) definitions, not the raw waveform data they reference.

memory.ClearSequences()

Sequence

Removes every loaded sequence (parsed MML data) from memory.

③ Playback control package player

player.Play(engine Engine, sequenceID string, onComplete func()) error

Playback

Starts asynchronous playback of a loaded sequence (the caller is never blocked). Anything already playing is stopped first. When a non-looping song finishes playing through to its end, onComplete (if non-nil) is called exactly once from a background goroutine. If the sequence's [global] has startOffset set, playback begins at that position.

player.SkipPlay(engine Engine, sequenceID string, seekSeconds float64, onComplete func()) error

Playback

Same as Play, but starts playback seekSeconds seconds into the song instead of at the beginning. If that position falls in the middle of a note, playback rewinds to that note's own start.

player.FadeInPlay(engine Engine, sequenceID string, fadeSeconds float64, onComplete func()) error

Playback / Fade

Starts at volume 0 and glides smoothly up to [global]'s volume over fadeSeconds while playing.

player.FadeOutPlay(engine Engine, sequenceID string, fadeSeconds float64, onComplete func()) error

Playback / Fade

Begins fading out fadeSeconds seconds before the song's end, timed to reach volume 0 exactly as the song ends. A loop: true song has no automatic fade-out (behaves exactly like Play).

player.FadeInOutPlay(engine Engine, sequenceID string, fadeSeconds float64, onComplete func()) error

Playback / Fade

Combines FadeInPlay and FadeOutPlay.

player.FadeOut(fadeSeconds float64) error

Fade

Fades the currently playing sequence's master volume down to 0 over fadeSeconds, starting from any moment, and stops playback once it reaches 0. Unlike FadeOutPlay's automatic end-of-song fade, this can be called explicitly at any time and applies even to a loop: true song.

player.SetMasterVolume(engine Engine, volume float64)

Volume

Overwrites the master volume with a real value on the same 0-127 scale as [global]'s volume. If called during playback it glides smoothly over about 0.3 seconds; otherwise it takes effect immediately.

player.SetMasterVolumePercent(engine Engine, percent float64)

Volume

Sets the master volume as a percentage, where 100 equals the most recently loaded sequence's own [global] volume value (50 = half that volume). The same smooth-glide-during-playback behavior as SetMasterVolume applies.

player.Pause() error

Playback control

Pauses the currently playing sequence in place (with a short fade-out to avoid a click). Returns an error if nothing is playing.

player.Resume() error

Playback control

Resumes a sequence previously paused with Pause. If playback was paused mid-note, it rewinds to that note's own start before resuming.

player.Stop() error

Playback control

Halts the currently playing (or paused) sequence entirely.

player.IsPlaying() bool

State query

Reports whether a sequence is actively playing right now (false while paused or when nothing has ever played).

player.Rewind() error

Playback control

Resets playback position to the very start (tick 0). If playback is active, it restarts from the beginning immediately; if paused, the next Resume will start from the beginning.

④ FM/PCM core low-level API package fmcore

Use these when you want to control voice registration and note-triggering directly in code, without going through MML. fmcore.Engine contains both the FM and PCM sound cores.

fmcore.NewEngine(sampleRate int) (*Engine, error)

Init

Opens an audio output device (initializing an oto/v3 context internally) and creates an engine at the given sample rate.

fmcore.NewEngineWithoutOutput(sampleRate int) *Engine

Init

Creates an engine without opening an audio device. Since *Engine itself implements io.Reader, it can be registered as a player on an oto.Context your app already owns.

(*Engine) RegisterVoice(id VoiceID, voice Voice)

Voice registration

Registers an FM voice's parameters (operators, envelopes, algorithm) under an ID, in memory.

(*Engine) SetPart(id PartID, voice VoiceID, volume, pan float64) error

Part setup

Assigns a voice ID, volume, and pan to a given sounding part.

(*Engine) NoteOnRow(partID PartID, noteNumber uint8, durationMs int, velocity uint8) (NoteID, error)

Note-on

Triggers a note using a raw note number, duration in ms, and velocity. Returns a note ID immediately; the note itself continues sounding asynchronously.

(*Engine) NoteOn(partID PartID, noteName string, noteType string, sustain int, velocity uint8) (NoteID, error)

Note-on

The abstracted counterpart: takes a note name like "C#5", a note-type name like "NOTE4", a sustain percentage, and a velocity, converting internally to a note number and duration in ms.

(*Engine) RegisterPCMVoice(id pcmcore.VoiceID, voice pcmcore.Voice)

PCM voice registration

Registers a PCM voice (oneShot or long).

(*Engine) SetPCMPart(id pcmcore.PartID, voice pcmcore.VoiceID, volume, pan float64) error

PCM part setup

Assigns a voice, volume, and pan to a given PCM part ('A' through 'P').

(*Engine) SetMasterVolume(volume float64) / SetMasterVolumeSmooth(target, rampSeconds float64)

Volume

Sets the engine-wide master volume (0.0-1.0), instantly or with a smooth ramp. The player package's volume API is a wrapper over these.

(*Engine) SetReverb(enabled bool, kind string, timeSeconds, level float64) / SetPartReverbSend(id PartID, send float64)

Reverb

Enables/configures the master reverb (type: "simple" = Schroeder, "normal" = FDN, plus reverb time and level), and sets a per-part send level.

(*Engine) Close() error

Shutdown

Closes the audio output device (when opened via NewEngine).

The above is an excerpt of the main methods intended to be called directly from an application. The Schedule* methods (ScheduleNoteOn and similar - a sample-accurate, low-level API for scheduling note timing) are mostly used by player's own internal implementation, but are also available if you're building your own sequencer. See the source code's own comments for details.