// The MIT License (MIT)
//
// Copyright (C) 2026 Scott Duensing
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
// IN THE SOFTWARE.

// audio.h  -- sound library (audio.lib)
//
// Sound for DVX programs through whatever sound hardware the computer
// has.  Every program opens its own audio context; any number of
// programs play at the same time through one mixer, and everything a
// program opened is stopped and released when it ends, however it ends.
//
//   Samples   a sound loaded from a WAV or VOC file (or memory, or raw
//             PCM) and played on voices: volume, pan, pitch, looping,
//             an end notification.
//   Tones     square, triangle and noise tones of a frequency and length,
//             made by the mixer (on the PC speaker by its tone generator).
//   Streams   a program's own sound (music, speech) at any rate: it
//             writes samples, or the library asks for them.
//   Notes     a queue of tones and rests played back to back, each to the
//             exact sample (melodies; QBasic's PLAY and SOUND).
//   Volume    one master volume for the whole system and one per
//             context.
//   FM        the FM synthesizer chip (OPL2 / OPL3), when there is one:
//             two-operator voices shared by every program (tones use
//             them too), or the whole chip for one program at a time.
//   MIDI      the MIDI port (MPU-401), for one program at a time.
//   Desktop   the sounds DVX plays for its own events (starting, message
//   sounds    boxes, ...), chosen in DVX.INI [sounds].
//
// The mixer works in 16-bit integers at the rate the sound device
// achieved (22,050 Hz unless DVX.INI [audio] rate says otherwise),
// resamples every source with linear interpolation and clips the sum.
// It mixes from the device's own interrupt (or the timer service for
// devices without one), so sound keeps playing however busy the
// programs are.  At most the configured voice limit plays at once;
// starting one more drops the quietest.
//
// Square and triangle tones play on a free FM voice when the computer
// has an FM chip (DVX.INI [audio] fmTones), else - or when every FM voice
// is taken - the mixer makes them.
//
// Devices come from driver modules (audioDrv.h) found at start-up:
// the one named by DVX.INI [audio] driver, else the Sound Blaster
// family, the PC speaker and finally the silent null driver, which
// keeps programs working on a computer without sound.
//
// Functions returning int32_t return AUDIO_OK or a voice id (> 0) on
// success and a negative AUDIO_ERR_* code on failure (audioErrorText
// says what it means).  Nothing here may be called from an interrupt.
#ifndef AUDIO_LIB_H
#define AUDIO_LIB_H

#include "dvxApp.h"
#include "dvxPrefs.h"
#include "dvxTypes.h"

#include <stdbool.h>
#include <stdint.h>

// Volume of a voice, a context or the master: 0 (silent) .. AUDIO_VOLUME_MAX
#define AUDIO_VOLUME_MAX        256

// Pan of a voice: AUDIO_PAN_LEFT .. AUDIO_PAN_RIGHT (centre plays at full
// volume on both sides; panning turns the other side down)
#define AUDIO_PAN_LEFT          (-256)
#define AUDIO_PAN_CENTER        0
#define AUDIO_PAN_RIGHT         256

// Pitch of a voice as a speed ratio in 1/256ths: AUDIO_PITCH_NORMAL plays
// at the recorded speed, twice that an octave higher.
#define AUDIO_PITCH_NORMAL      256
#define AUDIO_PITCH_MIN         64
#define AUDIO_PITCH_MAX         1024

// Sample rates a sound, a stream or the device may have (Hz)
#define AUDIO_RATE_MIN          4000
#define AUDIO_RATE_MAX          48000
#define AUDIO_RATE_DEFAULT      22050

// Tone frequencies (Hz)
#define AUDIO_TONE_MIN_HZ       20
#define AUDIO_TONE_MAX_HZ       20000

// Voices: the most that can exist, and the default limit of voices mixed
// at once (DVX.INI [audio] voices, 1..AUDIO_VOICES_MAX)
#define AUDIO_VOICES_MAX        32
#define AUDIO_VOICES_DEFAULT    16

// Note queues: the most entries (tones and rests) waiting to start, and
// the unit of their frequencies (1/1000 Hz; 0 is a rest)
#define AUDIO_NOTES_MAX         256
#define AUDIO_MILLIHZ_PER_HZ    1000

// Stream buffer length (milliseconds of sound)
#define AUDIO_STREAM_MS_MIN     20
#define AUDIO_STREAM_MS_DEFAULT 250
#define AUDIO_STREAM_MS_MAX     2000

// Text sizes in AudioInfoT (with the terminating zero)
#define AUDIO_NAME_MAX          16
#define AUDIO_DESC_MAX          64

// Results
#define AUDIO_OK                0
#define AUDIO_ERR_ARG           (-1)    // a bad argument
#define AUDIO_ERR_NO_MEMORY     (-2)    // out of memory
#define AUDIO_ERR_OPEN          (-3)    // the file could not be read
#define AUDIO_ERR_FORMAT        (-4)    // not a WAV or VOC file
#define AUDIO_ERR_UNSUPPORTED   (-5)    // compressed or unusual sound data
#define AUDIO_ERR_CORRUPT       (-6)    // damaged or incomplete file
#define AUDIO_ERR_NO_VOICE      (-7)    // voice limit reached, and this sound is the quietest
#define AUDIO_ERR_NO_DEVICE     (-8)    // no sound driver could be started
#define AUDIO_ERR_VOICE         (-9)    // no such voice in this context (ended, or never was)
#define AUDIO_ERR_BUSY          (-10)   // the synthesizer is in use by another program, or not ready
#define AUDIO_ERR_NO_SYNTH      (-11)   // no such synthesizer (no FM chip, no MIDI port)
#define AUDIO_ERR_COUNT         12      // AUDIO_OK and the eleven errors

// Opaque handles
typedef struct AudioCtxT    AudioCtxT;
typedef struct AudioNotesT  AudioNotesT;
typedef struct AudioSampleT AudioSampleT;
typedef struct AudioStreamT AudioStreamT;

// Tone waveforms
typedef enum {
    AUDIO_WAVE_SQUARE   = 0,
    AUDIO_WAVE_TRIANGLE = 1,
    AUDIO_WAVE_NOISE    = 2
} AudioWaveE;

// Why a voice ended
typedef enum {
    AUDIO_END_FINISHED = 0,    // played to its end (or its tone length)
    AUDIO_END_STOPPED  = 1,    // audioVoiceStop, audioStopAll, its sample or stream closed
    AUDIO_END_DROPPED  = 2     // the voice limit dropped it for a louder sound
} AudioEndE;

// PCM layout: rate in Hz, 8 (unsigned) or 16 (signed, little-endian)
// bits, 1 or 2 channels (stereo interleaved left, right).
typedef struct {
    uint32_t rate;
    uint32_t bits;
    uint32_t channels;
} AudioFormatT;

// The sound device in use (audioGetInfo).
typedef struct {
    char     driver[AUDIO_NAME_MAX];        // driver name ("sb", "speaker", "null"); "" when none runs
    char     description[AUDIO_DESC_MAX];   // for people, e.g. "Sound Blaster 16 (DSP 4.05)"
    uint32_t rate;                          // mixing rate the device achieved (Hz)
    uint32_t bits;                          // output bits
    uint32_t channels;                      // output channels
    uint32_t voiceLimit;                    // voices mixed at once
    bool     running;                       // a device is playing (some context is open)
    bool     hasDac;                        // plays sampled sound (else tones only, or nothing)
    bool     hasSynth;                      // has a hardware music synthesizer
    bool     hasTone;                       // plays tones on a hardware tone generator
} AudioInfoT;

// Mixer counters since the device started (audioGetStats).
typedef struct {
    uint32_t renders;      // blocks the device asked the mixer for
    uint32_t frames;       // frames mixed
    uint32_t underruns;    // stream frames that were due but not yet written
    uint32_t clipped;      // output samples clipped to the 16-bit range
    uint32_t dropped;      // voices dropped (or refused) by the voice limit
    uint32_t playing;      // voices playing now
} AudioStatsT;

// A voice of ctx ended.  Called from audioPump or the shell's idle time,
// never from an interrupt, as the program that owns ctx.
typedef void (*AudioEndFnT)(AudioCtxT *ctx, int32_t voice, AudioEndE reason, void *userData);

// A pull stream wants up to frames frames in its own format in buf.
// Return how many were written (fewer, even 0, is fine: the rest is asked
// for later).  Called from audioPump or the shell's idle time.
typedef uint32_t (*AudioFillFnT)(AudioStreamT *stream, void *buf, uint32_t frames, void *userData);

// ============================================================
// Contexts, device and volume
// ============================================================

// Open an audio context for the calling program; the first one opened
// starts the sound device.  NULL when out of memory or when no driver
// could be started.  Every context is closed for its program when the
// program ends.
AudioCtxT *audioOpen(void);

// Stop every voice of ctx, free its samples and streams and close it; the
// last one closed stops the device.  NULL is ignored.
void audioClose(AudioCtxT *ctx);

// Text for an AUDIO_OK / AUDIO_ERR_* code.
const char *audioErrorText(int32_t err);

// The device in use (running false and driver "" while none is open).
void audioGetInfo(AudioInfoT *info);

// Mixer counters since the device started.
void audioGetStats(AudioStatsT *stats);

// Master volume of all sound (0..AUDIO_VOLUME_MAX; DVX.INI [audio]
// volume, in percent, sets it when the device starts).
int32_t audioGetMasterVolume(void);
void    audioSetMasterVolume(int32_t volume);

// Volume of everything ctx plays (0..AUDIO_VOLUME_MAX, default the
// maximum).
int32_t audioGetVolume(const AudioCtxT *ctx);
void    audioSetVolume(AudioCtxT *ctx, int32_t volume);

// Call fn when a voice of ctx ends (NULL: no calls).
void audioSetEndFn(AudioCtxT *ctx, AudioEndFnT fn, void *userData);

// Deliver end notifications and fill pull streams now.  The shell does
// this in its idle time; a program that keeps the desktop busy every
// frame should call it once a frame.
void audioPump(void);

// Stop every voice of ctx.
void audioStopAll(AudioCtxT *ctx);

// ============================================================
// Samples and voices
// ============================================================

// Load a WAV (PCM, 8 or 16 bits, mono or stereo, any other chunks
// skipped) or VOC (8-bit, 16-bit, silence and extended blocks) sound from
// a file or from memory.
int32_t audioSampleLoad(AudioCtxT *ctx, const char *path, AudioSampleT **out);
int32_t audioSampleLoadMem(AudioCtxT *ctx, const void *data, uint32_t size, AudioSampleT **out);

// A sample from raw PCM frames in format fmt.
int32_t audioSampleCreate(AudioCtxT *ctx, const void *pcm, uint32_t frames, const AudioFormatT *fmt, AudioSampleT **out);

// Stop the voices playing it and free it.  NULL is ignored.
void audioSampleFree(AudioSampleT *sample);

// The sample's recorded format and length in frames.
void audioSampleInfo(const AudioSampleT *sample, AudioFormatT *fmt, uint32_t *frames);

// Play sample on a new voice at volume and pan, from its start, once or
// looping until stopped.  Returns the voice id.
int32_t audioPlay(AudioSampleT *sample, int32_t volume, int32_t pan, bool loop);

// Load a sound file and play it; the sample is freed when the voice ends.
int32_t audioPlayFile(AudioCtxT *ctx, const char *path, int32_t volume, int32_t pan, bool loop);

// Play a tone of hz for ms milliseconds (0: until stopped).
int32_t audioTone(AudioCtxT *ctx, AudioWaveE wave, uint32_t hz, int32_t volume, uint32_t ms);

// Change or stop a voice of ctx; AUDIO_ERR_VOICE when it is not one
// (any more).  Pitch changes a sample's or stream's speed (and a tone's
// frequency); SetFrequency sets a tone's frequency.
int32_t audioVoiceSetFrequency(AudioCtxT *ctx, int32_t voice, uint32_t hz);
int32_t audioVoiceSetPan(AudioCtxT *ctx, int32_t voice, int32_t pan);
int32_t audioVoiceSetPitch(AudioCtxT *ctx, int32_t voice, int32_t pitch);
int32_t audioVoiceSetVolume(AudioCtxT *ctx, int32_t voice, int32_t volume);
int32_t audioVoiceStop(AudioCtxT *ctx, int32_t voice);

// True while the voice of ctx is still playing.
bool audioVoiceIsPlaying(const AudioCtxT *ctx, int32_t voice);

// ============================================================
// Streams
// ============================================================

// Open a stream of format fmt with a buffer of bufferMs milliseconds (0:
// AUDIO_STREAM_MS_DEFAULT).  It starts playing at once on its own voice
// (silence until samples arrive).  With fill, the library asks for
// samples whenever the buffer has room; without, the program writes them
// with audioStreamWrite.
int32_t audioStreamOpen(AudioCtxT *ctx, const AudioFormatT *fmt, uint32_t bufferMs, AudioFillFnT fill, void *userData, AudioStreamT **out);

// Stop and free the stream.  NULL is ignored.
void audioStreamClose(AudioStreamT *stream);

// Frames buffered and not yet played, and frames of room left.
uint32_t audioStreamQueued(const AudioStreamT *stream);
uint32_t audioStreamSpace(const AudioStreamT *stream);

// The stream's voice id (for volume, pan and pitch).
int32_t audioStreamVoice(const AudioStreamT *stream);

// Append up to frames frames in the stream's format; returns how many fit.
uint32_t audioStreamWrite(AudioStreamT *stream, const void *pcm, uint32_t frames);

// ============================================================
// Note queues
// ============================================================
//
// Tones and rests played one after the other, each lasting exactly as
// long as asked (to the output frame, with no drift over a long tune) as
// long as the next is queued before the one before it ends.  A queue
// plays on its own voice, in the mixer or on the PC speaker's tone
// generator (never on the FM chip), and the voice limit never drops it;
// it is silent while empty.

// A queue of wave tones (square, triangle or noise) at volume
// (0..AUDIO_VOLUME_MAX; audioVoiceSetVolume on audioNotesVoice changes it).
int32_t audioNotesOpen(AudioCtxT *ctx, AudioWaveE wave, int32_t volume, AudioNotesT **out);

// Stop and free the queue.  NULL is ignored.
void audioNotesClose(AudioNotesT *notes);

// Append a tone of milliHz thousandths of a hertz (AUDIO_TONE_MIN_HZ ..
// AUDIO_TONE_MAX_HZ, or 0 for a rest) lasting us microseconds.
// AUDIO_ERR_BUSY when AUDIO_NOTES_MAX entries are already waiting.
int32_t audioNotesAdd(AudioNotesT *notes, uint32_t milliHz, uint32_t us);

// Silence the queue now and forget everything in it.
void audioNotesClear(AudioNotesT *notes);

// Entries not yet finished (playing or waiting; 0 when the queue has gone
// quiet); tones, when not NULL, gets how many of them are tones rather
// than rests.
uint32_t audioNotesQueued(const AudioNotesT *notes, uint32_t *tones);

// Entries that can still be added.
uint32_t audioNotesSpace(const AudioNotesT *notes);

// The queue's voice id (for volume and pan).
int32_t audioNotesVoice(const AudioNotesT *notes);

// ============================================================
// FM synthesizer
// ============================================================
//
// The FM chip's two-operator voices are shared: a program takes one with
// audioFmAlloc, programs it with audioFmWrite and gives it back with
// audioFmFree (closing the context gives back all of its voices).  Voices
// are handed out least recently used first, so a released note's tail
// is cut last.  audioFmWrite takes the registers of the voice's own
// channel, numbered as for the first channel of an OPL2 (AUDIO_FM_*
// below); the library adds the channel's offsets.  On an OPL3 a
// AUDIO_FM_FEEDBACK value without either output bit plays on both sides.
//
// A program may instead take the whole chip (audioFmRawAcquire): every
// voice of the other programs is silenced and taken back (their tones
// go on in the mixer), new voices are refused until the chip is given
// back, and a second program asking for the chip gets AUDIO_ERR_BUSY.
//
// audioFmAlloc, audioFmFree, audioFmWrite and audioFmRawWrite may also be
// called from a timer callback (platformTimerAdd), as music playback does.

// Most voices an FM chip has (OPL3; an OPL2 has 9)
#define AUDIO_FM_VOICES_MAX     18

// The chip's own sample rate (Hz), which frequency numbers are based on:
// hz = fnum * AUDIO_FM_CHIP_HZ * 2^block / 2^20
#define AUDIO_FM_CHIP_HZ        49716
#define AUDIO_FM_FNUM_MAX       1023
#define AUDIO_FM_BLOCK_MAX      7
#define AUDIO_FM_FNUM_HI_SHIFT  8       // fnum bits 8-9 go in AUDIO_FM_KEY_BLOCK bits 0-1
#define AUDIO_FM_BLOCK_SHIFT    2       // block in AUDIO_FM_KEY_BLOCK bits 2-4

// Channel registers for audioFmWrite (modulator / carrier operator)
#define AUDIO_FM_MOD_CHAR       0x20    // tremolo, vibrato, sustaining, key scale rate, multiple
#define AUDIO_FM_CAR_CHAR       0x23
#define AUDIO_FM_MOD_LEVEL      0x40    // key scale level (bits 6-7), attenuation (bits 0-5, 0.75 dB)
#define AUDIO_FM_CAR_LEVEL      0x43
#define AUDIO_FM_MOD_ATTACK     0x60    // attack rate (bits 4-7), decay rate (bits 0-3)
#define AUDIO_FM_CAR_ATTACK     0x63
#define AUDIO_FM_MOD_SUSTAIN    0x80    // sustain level (bits 4-7), release rate (bits 0-3)
#define AUDIO_FM_CAR_SUSTAIN    0x83
#define AUDIO_FM_FNUM_LOW       0xA0    // frequency number bits 0-7
#define AUDIO_FM_KEY_BLOCK      0xB0    // key on, block, frequency number bits 8-9
#define AUDIO_FM_FEEDBACK       0xC0    // outputs, feedback (bits 1-3), additive (bit 0)
#define AUDIO_FM_MOD_WAVE       0xE0    // waveform
#define AUDIO_FM_CAR_WAVE       0xE3

// Bits of those registers
#define AUDIO_FM_KEY_ON         0x20    // AUDIO_FM_KEY_BLOCK: sounding
#define AUDIO_FM_OUT_LEFT       0x10    // AUDIO_FM_FEEDBACK: left output (OPL3)
#define AUDIO_FM_OUT_RIGHT      0x20    // AUDIO_FM_FEEDBACK: right output (OPL3)
#define AUDIO_FM_OUT_BOTH       (AUDIO_FM_OUT_LEFT | AUDIO_FM_OUT_RIGHT)
#define AUDIO_FM_ADDITIVE       0x01    // AUDIO_FM_FEEDBACK: both operators heard

// The FM chip (audioFmGetInfo); voices 0 when there is none.
typedef struct {
    char     description[AUDIO_DESC_MAX];   // e.g. "OPL3 FM synthesizer at 388h"
    uint32_t voices;                        // two-operator voices
    uint32_t freeVoices;                    // not taken by any program
    bool     stereo;                        // voices can be panned (OPL3)
    bool     rawOwned;                      // one program has the whole chip
} AudioFmInfoT;

// Take a free FM voice for ctx.  Returns its id (> 0), AUDIO_ERR_NO_VOICE
// when all are taken, AUDIO_ERR_BUSY while a program has the whole chip,
// AUDIO_ERR_NO_SYNTH without an FM chip.
int32_t audioFmAlloc(AudioCtxT *ctx);

// Silence the voice (key off) and give it back.
int32_t audioFmFree(AudioCtxT *ctx, int32_t voice);

// The FM chip in use.
void audioFmGetInfo(AudioFmInfoT *info);

// Set a register of the voice's channel (AUDIO_FM_*).
int32_t audioFmWrite(AudioCtxT *ctx, int32_t voice, uint8_t reg, uint8_t value);

// The whole chip for ctx alone; audioFmRawWrite sets any register
// (bank * AUDIO_FM_BANK_REGS + index, bank 1 on an OPL3 only).  Release
// silences the chip and gives its voices back to everyone.
int32_t audioFmRawAcquire(AudioCtxT *ctx);
int32_t audioFmRawRelease(AudioCtxT *ctx);
int32_t audioFmRawWrite(AudioCtxT *ctx, uint32_t reg, uint8_t value);

// ============================================================
// MIDI port
// ============================================================
//
// The MIDI port (an MPU-401 in UART mode, used only when DVX.INI [audio]
// midi = mpu401) belongs to one program at a time.  audioMidiPut may
// also be called from a timer callback; it returns AUDIO_ERR_BUSY when
// the port cannot take a byte yet (send it again later).

// The MIDI port (audioMidiGetInfo).
typedef struct {
    char description[AUDIO_DESC_MAX];   // e.g. "MPU-401 MIDI port at 330h"; "" when none
    bool present;
    bool owned;                         // a program is using it
} AudioMidiInfoT;

int32_t audioMidiAcquire(AudioCtxT *ctx);
void    audioMidiGetInfo(AudioMidiInfoT *info);
int32_t audioMidiPut(AudioCtxT *ctx, uint8_t byte);
int32_t audioMidiRelease(AudioCtxT *ctx);

// ============================================================
// Desktop sounds
// ============================================================
//
// The sounds DVX plays for its events (dvxPlaySound, DvxSoundE in
// dvxApp.h).  Each event's sound is a WAV or VOC file named in DVX.INI
// [sounds] under the event's key: a name alone is a file in the sound
// folders (the user's SOUNDS, then SHARED\SOUNDS: platformKindFind), a
// name with a folder in it a path (empty or missing: none).  The library
// connects itself to DVX when it loads and plays them on a context of its
// own, so they belong to no program; with no sound hardware they are
// silent.

#define AUDIO_SOUNDS_SECTION    "sounds"

// The DVX.INI key of an event ("startup", "error", ...), and its name for
// people ("Start DVX", "Error", ...); NULL for an event out of range.
const char *audioDeskKey(DvxSoundE event);
const char *audioDeskLabel(DvxSoundE event);

// Play the event's sound (the DvxSoundHookT that DVX calls); with wait,
// return once it has played (at most a few seconds).
void audioDeskPlay(DvxSoundE event, bool wait);

// Play a sound file the way desktop sounds play (to try one out).
// Returns the voice id or an AUDIO_ERR_* code.
int32_t audioDeskPlayFile(const char *path);

// DVX.INI [sounds] has changed: read it again before the next sound.
void audioDeskReload(void);

// ============================================================
// Drivers
// ============================================================

// The short names of the sound drivers installed (DVX.INI [audio]
// driver), the one tried first first; returns how many were put in names
// (at most max).
int32_t audioDriverNames(char names[][AUDIO_NAME_MAX], int32_t max);

// The most drivers audioDriverNames is asked for by DVX's own callers
#define AUDIO_DRIVERS_MAX       16

// ============================================================
// Settings (DVX.INI, the Control Panel's Sounds page)
// ============================================================
//
// What the Sounds page and the BASIC functions read and write; prefs is
// a copy of DVX.INI the caller loads and saves.  The device reads the
// same keys when it starts (driver, volume, midi: audioDrv.h).

// [audio] midi: where MIDI music plays, in dropdown order (label for
// people, iniName stored; value unused).  Default AUDIO_MIDI_AUTO.
#define AUDIO_MIDI_CHOICE_COUNT 4
extern const PrefsChoiceT audioMidiChoices[AUDIO_MIDI_CHOICE_COUNT];

// The sound file of an event in [sounds] ("" for none or an event out of
// range), and setting it ("" or NULL: none).
const char *audioDeskFile(PrefsHandleT *prefs, DvxSoundE event);
void        audioDeskSetFile(PrefsHandleT *prefs, DvxSoundE event, const char *path);

// A volume in percent (clamped to 0..100) as 0..AUDIO_VOLUME_MAX.
int32_t audioPercentToVolume(int32_t percent);

// [audio] driver (AUDIO_DRIVER_AUTO when missing), midi (the index in
// audioMidiChoices; auto when missing or unknown) and volume (percent,
// 0..100, 100 when missing).
const char *audioSettingDriver(PrefsHandleT *prefs);
int32_t     audioSettingMidi(PrefsHandleT *prefs);
int32_t     audioSettingVolume(PrefsHandleT *prefs);

// Store [audio] driver, midi (an audioMidiChoices index; out of range:
// auto) and volume (percent, clamped).
void audioSettingsStore(PrefsHandleT *prefs, const char *driver, int32_t midi, int32_t volume);

// ============================================================
// BASIC (src/include/basic/sound.bas)
// ============================================================

// Each BASIC program gets its own context on first use.  Volumes, pans
// and pitches are in percent (volume 0..100, pan -100..100, pitch
// 25..400); a voice, sound or stream number is 0 on failure (SoundError$
// says why).  Sounds and streams are numbered per program and freed with
// its context.  SoundCreate and SoundStreamWrite take BINARY STRING PCM
// (bytes and byte count).  The Midi... functions are declared in
// music.bas.
int32_t     FmAlloc(void);
void        FmFree(int32_t voice);
const char *FmInfo(const char *field);
int32_t     FmRawAcquire(void);
void        FmRawRelease(void);
int32_t     FmRawWrite(int32_t reg, int32_t value);
int32_t     FmWrite(int32_t voice, int32_t reg, int32_t value);
int32_t     MidiAcquire(void);
const char *MidiPortInfo(const char *field);
int32_t     MidiPut(int32_t byteValue);
void        MidiRelease(void);
int32_t     PlayNoise(int32_t frequency, int32_t milliseconds, int32_t volume);
int32_t     PlayTone(int32_t frequency, int32_t milliseconds, int32_t volume);
int32_t     PlayTriangle(int32_t frequency, int32_t milliseconds, int32_t volume);
int32_t     PlayWave(const char *fileName);
int32_t     PlayWaveLoop(const char *fileName);
int32_t     SoundCaps(const char *field);
int32_t     SoundCreate(const uint8_t *pcm, int32_t len, int32_t rate, int32_t bits, int32_t channels);
const char *SoundDriverAuto(void);
int32_t     SoundDriverCount(void);
const char *SoundDriverName(int32_t index);
const char *SoundError(void);
int32_t     SoundEventCount(void);
const char *SoundEventFile(int32_t prefs, int32_t eventIdx);
const char *SoundEventKey(int32_t eventIdx);
const char *SoundEventLabel(int32_t eventIdx);
void        SoundEventsReload(void);
const char *SoundFolder(void);
void        SoundFree(int32_t sound);
int32_t     SoundGetVolume(void);
const char *SoundInfo(void);
int32_t     SoundLength(int32_t sound);
int32_t     SoundLoad(const char *fileName);
int32_t     SoundMasterVolume(void);
int32_t     SoundMidiCount(void);
const char *SoundMidiLabel(int32_t index);
int32_t     SoundPlay(int32_t sound, int32_t volume, int32_t pan, int32_t loopIt);
void        SoundPlayEvent(int32_t eventIdx, int32_t wait);
int32_t     SoundPlaying(int32_t voice);
void        SoundSetEventFile(int32_t prefs, int32_t eventIdx, const char *fileName);
void        SoundSetFrequency(int32_t voice, int32_t frequency);
void        SoundSetMasterVolume(int32_t percent);
void        SoundSetPan(int32_t voice, int32_t pan);
void        SoundSetPitch(int32_t voice, int32_t percent);
const char *SoundSettingDriver(int32_t prefs);
int32_t     SoundSettingMidi(int32_t prefs);
void        SoundSettingsStore(int32_t prefs, const char *driver, int32_t midi, int32_t volume);
int32_t     SoundSettingVolume(int32_t prefs);
void        SoundSetVolume(int32_t voice, int32_t volume);
void        SoundStreamClose(int32_t stream);
int32_t     SoundStreamOpen(int32_t rate, int32_t bits, int32_t channels, int32_t bufferMs);
int32_t     SoundStreamQueued(int32_t stream);
int32_t     SoundStreamSpace(int32_t stream);
int32_t     SoundStreamVoice(int32_t stream);
int32_t     SoundStreamWrite(int32_t stream, const uint8_t *pcm, int32_t len);
int32_t     SoundTestFile(const char *fileName);
void        SoundVolume(int32_t volume);
void        StopAllSounds(void);
void        StopWave(int32_t voice);

#endif // AUDIO_LIB_H