Defines functions for microphone creation, control, audio data fetching, and destruction. This module supports multiple calls to |SbMicrophoneOpen| and |SbMicrophoneClose|, and the implementation should handle multiple calls to one of those functions on the same microphone. For example, your implementation should handle cases where |SbMicrophoneOpen| is called twice on the same microphone without a call to |SbMicrophoneClose| in between.
This API is not thread-safe and must be called from a single thread.
How to use this API:
All possible microphone types.
Values
kSbMicrophoneCamera
- Built-in microphone in camera.kSbMicrophoneUSBHeadset
- Microphone in the headset that can be a wired or wireless USB headset.kSbMicrophoneVRHeadset
- Microphone in the VR headset.kSBMicrophoneAnalogHeadset
- Microphone in the analog headset.kSbMicrophoneUnknown
- Unknown microphone type. The microphone could be different than the otherenum descriptions or could fall under one of those descriptions.An opaque handle to an implementation-private structure that represents a microphone ID.
Microphone information.
Members
An opaque handle to an implementation-private structure that represents a microphone.
Description
Closes the microphone port, stops recording audio on microphone
, and clears the unread buffer if it is not empty. If the microphone has already been stopped, this call is ignored. The return value indicates whether the microphone is closed.
Declaration and definitions
#include "starboard/microphone.h" #if !SB_HAS(MICROPHONE) #error "SB_HAS_MICROPHONE must be set to build this file." #endif bool SbMicrophoneClose(SbMicrophone microphone) { return false; }
Parameters
Description
Creates a microphone with the specified ID, audio sample rate, and cached audio buffer size. Starboard only requires support for creating one microphone at a time, and implementations may return an error if a second microphone is created before the first is destroyed.
The function returns the newly created SbMicrophone object. However, if you try to create a microphone that has already been initialized, if the sample rate is unavailable, or if the buffer size is invalid, the function should return kSbMicrophoneInvalid
.
Declaration and definitions
#include "starboard/microphone.h" #if !SB_HAS(MICROPHONE) #error "SB_HAS_MICROPHONE must be set to build this file." #endif SbMicrophone SbMicrophoneCreate(SbMicrophoneId id, int sample_rate_in_hz, int buffer_size) { return kSbMicrophoneInvalid; }
Parameters
Description
Destroys a microphone. If the microphone is in started state, it is first stopped and then destroyed. Any data that has been recorded and not read is thrown away.
Declaration and definitions
#include "starboard/microphone.h" #if !SB_HAS(MICROPHONE) #error "SB_HAS_MICROPHONE must be set to build this file." #endif void SbMicrophoneDestroy(SbMicrophone microphone) {}
Parameters
Description
Retrieves all currently available microphone information and stores it in out_info_array
. The return value is the number of the available microphones. If the number of available microphones is larger than info_array_size
, then out_info_array
is filled up with as many available microphones as possible and the actual number of available microphones is returned. A negative return value indicates that an internal error occurred.
Declaration and definitions
#include "starboard/microphone.h" #if !SB_HAS(MICROPHONE) #error "SB_HAS_MICROPHONE must be set to build this file." #endif int SbMicrophoneGetAvailable(SbMicrophoneInfo* out_info_array, int info_array_size) { return 0; }
Parameters
Description
Indicates whether the given microphone ID is valid.
Declaration
static SB_C_INLINE bool SbMicrophoneIdIsValid(SbMicrophoneId id) { return id != kSbMicrophoneIdInvalid; }
Parameters
Description
Indicates whether the microphone supports the sample rate.
Declaration and definitions
#include "starboard/microphone.h" #if !SB_HAS(MICROPHONE) #error "SB_HAS_MICROPHONE must be set to build this file." #endif bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id, int sample_rate_in_hz) { return false; }
Parameters
Description
Indicates whether the given microphone is valid.
Declaration
static SB_C_INLINE bool SbMicrophoneIsValid(SbMicrophone microphone) { return microphone != kSbMicrophoneInvalid; }
Parameters
Description
Opens the microphone port and starts recording audio on microphone
.
Once started, the client needs to periodically call SbMicrophoneRead
to receive the audio data. If the microphone has already been started, this call clears the unread buffer. The return value indicates whether the microphone is open.
Declaration and definitions
#include "starboard/microphone.h" #if !SB_HAS(MICROPHONE) #error "SB_HAS_MICROPHONE must be set to build this file." #endif bool SbMicrophoneOpen(SbMicrophone microphone) { return false; }
Parameters
Description
Retrieves the recorded audio data from the microphone and writes that data to out_audio_data
.
The return value is zero or the positive number of bytes that were read. Neither the return value nor audio_data_size
exceeds the buffer size. A negative return value indicates that an error occurred.
This function should be called frequently. Otherwise, the microphone only buffers buffer_size
bytes as configured in SbMicrophoneCreate
and the new audio data is thrown out. No audio data is read from a stopped microphone.
Declaration and definitions
#include "starboard/microphone.h" #if !SB_HAS(MICROPHONE) #error "SB_HAS_MICROPHONE must be set to build this file." #endif int SbMicrophoneRead(SbMicrophone microphone, void* out_audio_data, int audio_data_size) { return -1; }
Parameters