git.sesse.net Git - pistorm/blob - raylib/raudio.h

   1 /**********************************************************************************************
   2 *
   3 *   raudio v1.0 - A simple and easy-to-use audio library based on miniaudio
   4 *
   5 *   FEATURES:
   6 *       - Manage audio device (init/close)
   7 *       - Load and unload audio files
   8 *       - Format wave data (sample rate, size, channels)
   9 *       - Play/Stop/Pause/Resume loaded audio
  10 *       - Manage mixing channels
  11 *       - Manage raw audio context
  12 *
  13 *   DEPENDENCIES:
  14 *       miniaudio.h  - Audio device management lib (https://github.com/dr-soft/miniaudio)
  15 *       stb_vorbis.h - Ogg audio files loading (http://www.nothings.org/stb_vorbis/)
  16 *       dr_mp3.h     - MP3 audio file loading (https://github.com/mackron/dr_libs)
  17 *       dr_flac.h    - FLAC audio file loading (https://github.com/mackron/dr_libs)
  18 *       jar_xm.h     - XM module file loading
  19 *       jar_mod.h    - MOD audio file loading
  20 *
  21 *   CONTRIBUTORS:
  22 *       David Reid (github: @mackron) (Nov. 2017):
  23 *           - Complete port to miniaudio library
  24 *
  25 *       Joshua Reisenauer (github: @kd7tck) (2015)
  26 *           - XM audio module support (jar_xm)
  27 *           - MOD audio module support (jar_mod)
  28 *           - Mixing channels support
  29 *           - Raw audio context support
  30 *
  31 *
  32 *   LICENSE: zlib/libpng
  33 *
  34 *   Copyright (c) 2014-2021 Ramon Santamaria (@raysan5)
  35 *
  36 *   This software is provided "as-is", without any express or implied warranty. In no event
  37 *   will the authors be held liable for any damages arising from the use of this software.
  38 *
  39 *   Permission is granted to anyone to use this software for any purpose, including commercial
  40 *   applications, and to alter it and redistribute it freely, subject to the following restrictions:
  41 *
  42 *     1. The origin of this software must not be misrepresented; you must not claim that you
  43 *     wrote the original software. If you use this software in a product, an acknowledgment
  44 *     in the product documentation would be appreciated but is not required.
  45 *
  46 *     2. Altered source versions must be plainly marked as such, and must not be misrepresented
  47 *     as being the original software.
  48 *
  49 *     3. This notice may not be removed or altered from any source distribution.
  50 *
  51 **********************************************************************************************/
  52
  53 #ifndef RAUDIO_H
  54 #define RAUDIO_H
  55
  56 //----------------------------------------------------------------------------------
  57 // Defines and Macros
  58 //----------------------------------------------------------------------------------
  59 // Allow custom memory allocators
  60 #ifndef RL_MALLOC
  61     #define RL_MALLOC(sz)       malloc(sz)
  62 #endif
  63 #ifndef RL_CALLOC
  64     #define RL_CALLOC(n,sz)     calloc(n,sz)
  65 #endif
  66 #ifndef RL_FREE
  67     #define RL_FREE(p)          free(p)
  68 #endif
  69
  70 //----------------------------------------------------------------------------------
  71 // Types and Structures Definition
  72 //----------------------------------------------------------------------------------
  73 #ifndef __cplusplus
  74 // Boolean type
  75     #if !defined(_STDBOOL_H)
  76         typedef enum { false, true } bool;
  77         #define _STDBOOL_H
  78     #endif
  79 #endif
  80
  81 // Wave type, defines audio wave data
  82 typedef struct Wave {
  83     unsigned int sampleCount;       // Total number of samples
  84     unsigned int sampleRate;        // Frequency (samples per second)
  85     unsigned int sampleSize;        // Bit depth (bits per sample): 8, 16, 32 (24 not supported)
  86     unsigned int channels;          // Number of channels (1-mono, 2-stereo)
  87     void *data;                     // Buffer data pointer
  88 } Wave;
  89
  90 typedef struct rAudioBuffer rAudioBuffer;
  91
  92 // Audio stream type
  93 // NOTE: Useful to create custom audio streams not bound to a specific file
  94 typedef struct AudioStream {
  95     unsigned int sampleRate;        // Frequency (samples per second)
  96     unsigned int sampleSize;        // Bit depth (bits per sample): 8, 16, 32 (24 not supported)
  97     unsigned int channels;          // Number of channels (1-mono, 2-stereo)
  98
  99     rAudioBuffer *buffer;           // Pointer to internal data used by the audio system
 100 } AudioStream;
 101
 102 // Sound source type
 103 typedef struct Sound {
 104     unsigned int sampleCount;       // Total number of samples
 105     AudioStream stream;             // Audio stream
 106 } Sound;
 107
 108 // Music stream type (audio file streaming from memory)
 109 // NOTE: Anything longer than ~10 seconds should be streamed
 110 typedef struct Music {
 111     int ctxType;                    // Type of music context (audio filetype)
 112     void *ctxData;                  // Audio context data, depends on type
 113
 114     bool looping;                   // Music looping enable
 115     unsigned int sampleCount;       // Total number of samples
 116
 117     AudioStream stream;             // Audio stream
 118 } Music;
 119
 120 #ifdef __cplusplus
 121 extern "C" {            // Prevents name mangling of functions
 122 #endif
 123
 124 //----------------------------------------------------------------------------------
 125 // Global Variables Definition
 126 //----------------------------------------------------------------------------------
 127 //...
 128
 129 //----------------------------------------------------------------------------------
 130 // Module Functions Declaration
 131 //----------------------------------------------------------------------------------
 132
 133 // Audio device management functions
 134 void InitAudioDevice(void);                                     // Initialize audio device and context
 135 void CloseAudioDevice(void);                                    // Close the audio device and context
 136 bool IsAudioDeviceReady(void);                                  // Check if audio device has been initialized successfully
 137 void SetMasterVolume(float volume);                             // Set master volume (listener)
 138
 139 // Wave/Sound loading/unloading functions
 140 Wave LoadWave(const char *fileName);                            // Load wave data from file
 141 Sound LoadSound(const char *fileName);                          // Load sound from file
 142 Sound LoadSoundFromWave(Wave wave);                             // Load sound from wave data
 143 void UpdateSound(Sound sound, const void *data, int samplesCount);// Update sound buffer with new data
 144 void UnloadWave(Wave wave);                                     // Unload wave data
 145 void UnloadSound(Sound sound);                                  // Unload sound
 146 void ExportWave(Wave wave, const char *fileName);               // Export wave data to file
 147 void ExportWaveAsCode(Wave wave, const char *fileName);         // Export wave sample data to code (.h)
 148
 149 // Wave/Sound management functions
 150 void PlaySound(Sound sound);                                    // Play a sound
 151 void StopSound(Sound sound);                                    // Stop playing a sound
 152 void PauseSound(Sound sound);                                   // Pause a sound
 153 void ResumeSound(Sound sound);                                  // Resume a paused sound
 154 void PlaySoundMulti(Sound sound);                               // Play a sound (using multichannel buffer pool)
 155 void StopSoundMulti(void);                                      // Stop any sound playing (using multichannel buffer pool)
 156 int GetSoundsPlaying(void);                                     // Get number of sounds playing in the multichannel
 157 bool IsSoundPlaying(Sound sound);                               // Check if a sound is currently playing
 158 void SetSoundVolume(Sound sound, float volume);                 // Set volume for a sound (1.0 is max level)
 159 void SetSoundPitch(Sound sound, float pitch);                   // Set pitch for a sound (1.0 is base level)
 160 void WaveFormat(Wave *wave, int sampleRate, int sampleSize, int channels);  // Convert wave data to desired format
 161 Wave WaveCopy(Wave wave);                                       // Copy a wave to a new wave
 162 void WaveCrop(Wave *wave, int initSample, int finalSample);     // Crop a wave to defined samples range
 163 float *GetWaveData(Wave wave);                                  // Get samples data from wave as a floats array
 164
 165 // Music management functions
 166 Music LoadMusicStream(const char *fileName);                    // Load music stream from file
 167 Music LoadMusicStreamFromMemory(const char *fileType, unsigned char* data, int dataSize); // Load module music from data
 168 void UnloadMusicStream(Music music);                            // Unload music stream
 169 void PlayMusicStream(Music music);                              // Start music playing
 170 void UpdateMusicStream(Music music);                            // Updates buffers for music streaming
 171 void StopMusicStream(Music music);                              // Stop music playing
 172 void PauseMusicStream(Music music);                             // Pause music playing
 173 void ResumeMusicStream(Music music);                            // Resume playing paused music
 174 bool IsMusicPlaying(Music music);                               // Check if music is playing
 175 void SetMusicVolume(Music music, float volume);                 // Set volume for music (1.0 is max level)
 176 void SetMusicPitch(Music music, float pitch);                   // Set pitch for a music (1.0 is base level)
 177 float GetMusicTimeLength(Music music);                          // Get music time length (in seconds)
 178 float GetMusicTimePlayed(Music music);                          // Get current music time played (in seconds)
 179
 180 // AudioStream management functions
 181 AudioStream InitAudioStream(unsigned int sampleRate, unsigned int sampleSize, unsigned int channels); // Init audio stream (to stream raw audio pcm data)
 182 void UpdateAudioStream(AudioStream stream, const void *data, int samplesCount); // Update audio stream buffers with data
 183 void CloseAudioStream(AudioStream stream);                      // Close audio stream and free memory
 184 bool IsAudioStreamProcessed(AudioStream stream);                // Check if any audio stream buffers requires refill
 185 void PlayAudioStream(AudioStream stream);                       // Play audio stream
 186 void PauseAudioStream(AudioStream stream);                      // Pause audio stream
 187 void ResumeAudioStream(AudioStream stream);                     // Resume audio stream
 188 bool IsAudioStreamPlaying(AudioStream stream);                  // Check if audio stream is playing
 189 void StopAudioStream(AudioStream stream);                       // Stop audio stream
 190 void SetAudioStreamVolume(AudioStream stream, float volume);    // Set volume for audio stream (1.0 is max level)
 191 void SetAudioStreamPitch(AudioStream stream, float pitch);      // Set pitch for audio stream (1.0 is base level)
 192 void SetAudioStreamBufferSizeDefault(int size);                 // Default size for new audio streams
 193
 194 #ifdef __cplusplus
 195 }
 196 #endif
 197
 198 #endif // RAUDIO_H