Starboard Module Reference: microphone.h

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:

  1. Call |SbMicrophoneGetAvailableInfos| to get a list of available microphone information.
  2. Create a supported microphone, using |SbMicrophoneCreate|, with enough buffer size and sample rate. Use |SbMicrophoneIsSampleRateSupported| to verify the sample rate.
  3. Use |SbMicrophoneOpen| to open the microphone port and start recording audio data.
  4. Periodically read out the data from microphone with |SbMicrophoneRead|.
  5. Call |SbMicrophoneClose| to close the microphone port and stop recording audio data.
  6. Destroy the microphone with |SbMicrophoneDestroy|.

Enums

SbMicrophoneType

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.

Structs

SbMicrophoneId

An opaque handle to an implementation-private structure that represents a microphone ID.

SbMicrophoneInfo

Microphone information.

Members

Members
SbMicrophoneId
id
Microphone id.
SbMicrophoneType
type
Microphone type.
int
max_sample_rate_hz
The microphone's maximum supported sampling rate.
int
min_read_size
The minimum read size required for each read from microphone.

SbMicrophone

An opaque handle to an implementation-private structure that represents a microphone.

Functions

SbMicrophoneClose

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

SB_EXPORT bool SbMicrophoneClose(SbMicrophone microphone);

#include "starboard/microphone.h"

#if SB_HAS(MICROPHONE) && SB_VERSION(2)

bool SbMicrophoneClose(SbMicrophone microphone) {
  return false;
}

#endif  // SB_HAS(MICROPHONE) && SB_VERSION(2)

Parameters

Parameters
SbMicrophone
microphone
The microphone to close.

SbMicrophoneCreate

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

SB_EXPORT SbMicrophone SbMicrophoneCreate(SbMicrophoneId id,
                                          int sample_rate_in_hz,
                                          int buffer_size_bytes);

#include "starboard/microphone.h"

#if SB_HAS(MICROPHONE) && SB_VERSION(2)

SbMicrophone SbMicrophoneCreate(SbMicrophoneId id,
                                int sample_rate_in_hz,
                                int buffer_size) {
  return kSbMicrophoneInvalid;
}

#endif  // SB_HAS(MICROPHONE) && SB_VERSION(2)

Parameters

Parameters
SbMicrophoneId
id
The ID that will be assigned to the newly created SbMicrophone.
int
sample_rate_in_hz
The new microphone's audio sample rate in Hz.
int
buffer_size_bytes
The size of the buffer where signed 16-bit integer audio data is temporarily cached to during the capturing. The audio data is removed from the audio buffer if it has been read, and new audio data can be read from this buffer in smaller chunks than this size. This parameter must be set to a value greater than zero and the ideal size is 2^n.

SbMicrophoneDestroy

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

SB_EXPORT void SbMicrophoneDestroy(SbMicrophone microphone);

#include "starboard/microphone.h"

#if SB_HAS(MICROPHONE) && SB_VERSION(2)

void SbMicrophoneDestroy(SbMicrophone microphone) {}

#endif  // SB_HAS(MICROPHONE) && SB_VERSION(2)

Parameters

Parameters
SbMicrophone
microphone

SbMicrophoneGetAvailable

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

SB_EXPORT int SbMicrophoneGetAvailable(SbMicrophoneInfo* out_info_array,
                                       int info_array_size);

#include "starboard/microphone.h"

#if SB_HAS(MICROPHONE) && SB_VERSION(2)

int SbMicrophoneGetAvailable(SbMicrophoneInfo* out_info_array,
                             int info_array_size) {
  return 0;
}

#endif  // SB_HAS(MICROPHONE) && SB_VERSION(2)

Parameters

Parameters
SbMicrophoneInfo*
out_info_array
All currently available information about the microphone is placed into this output parameter.
int
info_array_size
The size of out_info_array.

SbMicrophoneIdIsValid

Description

Indicates whether the given microphone ID is valid.

Declaration

static SB_C_INLINE bool SbMicrophoneIdIsValid(SbMicrophoneId id) {
  return id != kSbMicrophoneIdInvalid;
}

Parameters

Parameters
SbMicrophoneId
id

SbMicrophoneIsSampleRateSupported

Description

Indicates whether the microphone supports the sample rate.

Declaration and definitions

SB_EXPORT bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id,
                                                 int sample_rate_in_hz);

#include "starboard/microphone.h"

#if SB_HAS(MICROPHONE) && SB_VERSION(2)

bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id,
                                       int sample_rate_in_hz) {
  return false;
}

#endif  // SB_HAS(MICROPHONE) && SB_VERSION(2)

Parameters

Parameters
SbMicrophoneId
id
int
sample_rate_in_hz

SbMicrophoneIsValid

Description

Indicates whether the given microphone is valid.

Declaration

static SB_C_INLINE bool SbMicrophoneIsValid(SbMicrophone microphone) {
  return microphone != kSbMicrophoneInvalid;
}

Parameters

Parameters
SbMicrophone
microphone

SbMicrophoneOpen

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

SB_EXPORT bool SbMicrophoneOpen(SbMicrophone microphone);

#include "starboard/microphone.h"

#if SB_HAS(MICROPHONE) && SB_VERSION(2)

bool SbMicrophoneOpen(SbMicrophone microphone) {
  return false;
}

#endif  // SB_HAS(MICROPHONE) && SB_VERSION(2)

Parameters

Parameters
SbMicrophone
microphone
The microphone that will be opened and will start recording audio.

SbMicrophoneRead

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

SB_EXPORT int SbMicrophoneRead(SbMicrophone microphone,
                               void* out_audio_data,
                               int audio_data_size);

#include "starboard/microphone.h"

#if SB_HAS(MICROPHONE) && SB_VERSION(2)

int SbMicrophoneRead(SbMicrophone microphone,
                     void* out_audio_data,
                     int audio_data_size) {
  return -1;
}

#endif  // SB_HAS(MICROPHONE) && SB_VERSION(2)

Parameters

Parameters
SbMicrophone
microphone
The microphone from which to retrieve recorded audio data.
void*
out_audio_data
The buffer to which the retrieved data will be written.
int
audio_data_size
The number of requested bytes. If audio_data_size is smaller than min_read_size of SbMicrophoneInfo, the extra audio data that has already been read from the device is discarded.