audio.h

Go to the documentation of this file.

 
#ifndef OPENSNES_AUDIO_H
#define OPENSNES_AUDIO_H
 
#include <snes/types.h>
 
/* Removed on 2026-10-05 (1.0 plan, lot C): audioUpdate.
 * The replacements are in docs/UPGRADING.md; `make check-upgrade` names them. */
 
/*============================================================================
 * Constants
 *============================================================================*/


#define AUDIO_MAX_SAMPLES   64

#define AUDIO_MAX_VOICES    8

#define AUDIO_VOICE_AUTO    0xFF

#define AUDIO_VOICE_NONE    0xFF

#define AUDIO_VOL_MAX       127
#define AUDIO_VOL_MIN       0

#define AUDIO_PAN_LEFT      0
#define AUDIO_PAN_CENTER    8
#define AUDIO_PAN_RIGHT     15

#define AUDIO_PITCH_DEFAULT 0x1000

/* Pitch is a ratio to the sample's own rate (0x1000 = 1.0); these three
 * double per octave and assume a sample that plays just under middle C at
 * 0x1000 (~250 Hz). Until 2026-10-04 the comments were one octave off
 * their names (C3 called "Middle C"). */
#define AUDIO_PITCH_C3      0x085F  
#define AUDIO_PITCH_C4      0x10BE  
#define AUDIO_PITCH_C5      0x217C  

#define AUDIO_ATTACK_INSTANT    15
#define AUDIO_ATTACK_FAST       12
#define AUDIO_ATTACK_MEDIUM     8
#define AUDIO_ATTACK_SLOW       4

#define AUDIO_DECAY_NONE        0
#define AUDIO_DECAY_FAST        7
#define AUDIO_DECAY_MEDIUM      4
#define AUDIO_DECAY_SLOW        1

#define AUDIO_SUSTAIN_FULL      7
#define AUDIO_SUSTAIN_HALF      3
#define AUDIO_SUSTAIN_QUARTER   1

#define AUDIO_RELEASE_INSTANT   31
#define AUDIO_RELEASE_FAST      24
#define AUDIO_RELEASE_MEDIUM    16
#define AUDIO_RELEASE_SLOW      8

#define AUDIO_ECHO_DELAY_MIN    1   
#define AUDIO_ECHO_DELAY_MAX    7   

#define AUDIO_OK                0   
#define AUDIO_ERR_NO_MEMORY     1   
#define AUDIO_ERR_INVALID_ID    2   
#define AUDIO_ERR_NOT_LOADED    3   
#define AUDIO_ERR_TIMEOUT       4   

 
/*============================================================================
 * Data Types
 *============================================================================*/

typedef struct {
    u16 spcAddress;     
    u16 size;           
    u16 loopPoint;      
    u8  flags;          
    u8  reserved;       
} AudioSample;

typedef struct {
    u8  active;         
    u8  sampleId;       
    u8  volume;         
    u8  pan;            
    u16 pitch;          
} AudioVoiceState;
 
/*============================================================================
 * Initialization
 *============================================================================*/


u8 audioInit(void);

u8 audioIsReady(void);

 
/*============================================================================
 * Sample Management
 *============================================================================*/


u8 audioLoadSample(u8 id, const u8 *brrData, u16 size, u16 loopPoint);

void audioUnloadSample(u8 id);

u8 audioGetSampleInfo(u8 id, AudioSample *info);

u16 audioGetFreeMemory(void);

 
/*============================================================================
 * Playback Control
 *============================================================================*/


u8 audioPlaySample(u8 sampleId);

u8 audioPlaySampleEx(u8 sampleId, u8 volume, u8 pan, u16 pitch);

u8 audioPlaySampleOn(u8 voice, u8 sampleId, u8 volume, u8 pan, u16 pitch);

u8 audioStopVoice(u8 voice);

u8 audioStopAll(void);

 
/*============================================================================
 * Volume Control
 *============================================================================*/


u8 audioSetVolume(u8 volume);

u8 audioGetVolume(void);

u8 audioSetVoiceVolume(u8 voice, u8 volumeL, u8 volumeR);

u8 audioSetVoicePitch(u8 voice, u16 pitch);

void audioGetVoiceState(u8 voice, AudioVoiceState *state);

 
/*============================================================================
 * ADSR Envelope Control
 *============================================================================*/


u8 audioSetADSR(u8 voice, u8 attack, u8 decay, u8 sustain, u8 release);

u8 audioSetGain(u8 voice, u8 mode);

 
/*============================================================================
 * Echo/Reverb Effects
 *============================================================================*/


u8 audioSetEcho(u8 delay, s8 feedback, s8 volumeL, s8 volumeR);

u8 audioSetEchoFilter(const s8 fir[8]);

u8 audioEnableEcho(u8 voiceMask);

u8 audioDisableEcho(void);

 
/*============================================================================
 * Legacy API (backward compatibility)
 *============================================================================*/


#define audioStop() audioStopAll()

#define audioStopSample(id) audioStopVoice(id)

#define audioSetPan(id, pan) /* No-op, use audioPlaySampleEx instead */

 
#endif /* OPENSNES_AUDIO_H */