NAME

       SDL_OpenAudioDevice - Open a specific audio device.

HEADER FILE

       Defined in SDL3/SDL_audio.h

SYNOPSIS

       #include "SDL3/SDL.h"

       SDL_AudioDeviceID SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);

DESCRIPTION

       You  can open both playback and recording devices through this function.  Playback devices will take data
       from bound audio streams, mix it, and send it to the hardware. Recording  devices  will  feed  any  bound
       audio streams with a copy of any incoming data.

       An  opened audio device starts out with no audio streams bound. To start audio playing, bind a stream and
       supply audio data to it. Unlike SDL2, there is no audio callback; you only bind audio  streams  and  make
       sure they have data flowing into them (however, you can simulate SDL2's semantics fairly closely by using

       SDL_OpenAudioDeviceStream
        instead of this function).

       If you don't care about opening a specific device, pass a devid of either

       SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or

       SDL_AUDIO_DEVICE_DEFAULT_RECORDING .  In this case, SDL will try to pick the most reasonable default, and
       may  also switch between physical devices seamlessly later, if the most reasonable default changes during
       the lifetime of this opened device (user changed the default in the OS's system preferences, the  default
       got  unplugged  so the system jumped to a new default, the user plugged in headphones on a mobile device,
       etc). Unless you have a good reason to choose a specific device, this is probably what you want.

       You may request a specific format for the audio device, but there is no promise  the  device  will  honor
       that  request  for  several  reasons. As such, it's only meant to be a hint as to what data your app will
       provide. Audio streams will accept data in whatever format you specify and manage conversion for  you  as
       appropriate.

       SDL_GetAudioDeviceFormat
        can  tell  you  the  preferred  format for the device before opening and the actual format the device is
       using after opening.

       It's legal to open the same device ID more than once; each successful open will generate  a  new  logical
       SDL_AudioDeviceID
        that  is  managed  separately  from  others on the same physical device. This allows libraries to open a
       device separately from the main app and bind its own streams without conflicting.

       It is also legal to open a device ID returned by a previous call to this function; doing so just  creates
       another  logical  device  on the same physical device. This may be useful for making logical groupings of
       audio streams.

       This function returns the opened device ID on success. This is a new, unique SDL_AudioDeviceID
        that represents a logical device.

       Some backends might offer arbitrary devices (for example, a networked audio protocol that can connect  to
       an  arbitrary  server).  For these, as a change from SDL2, you should open a default device ID and use an
       SDL hint to specify the target if you care, or otherwise let the backend figure out a reasonable default.
       Most backends don't offer anything like this, and often this would be an end user setting an  environment
       variable for their custom need, and not something an application should specifically manage.

       When   done   with   an  audio  device,  possibly  at  the  end  of  the  app's  life,  one  should  call
       SDL_CloseAudioDevice () on the returned device id.

FUNCTION PARAMETERS

       devid  the device instance id to open, or SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK
               or SDL_AUDIO_DEVICE_DEFAULT_RECORDING
               for the most reasonable default device.

       spec   the requested device configuration. Can be NULL to use reasonable defaults.

RETURN VALUE

       ( SDL_AudioDeviceID ) Returns the device ID on success or 0 on failure; call  SDL_GetError  ()  for  more
       information.

THREAD SAFETY

       It is safe to call this function from any thread.

AVAILABILITY

       This function is available since SDL 3.2.0.

SEE ALSO

       •(3), SDL_CloseAudioDevice(3), •(3), SDL_GetAudioDeviceFormat(3)

Simple Directmedia Layer                            SDL 3.2.8                             SDL_OpenAudioDevice(3)