AVAudioSession¶
Inherits: RefCounted < Object
Controls the shared iOS/tvOS audio session from GDScript.
Description¶
Use this helper to select one of Apple’s predefined AVAudioSession categories so your Godot project can mix or duck audio according to platform expectations. It is most useful on mobile builds where the engine needs to share the audio device with the system music player or with voice chat as described in GameCenterGuide.md. See Apple’s audio session overview at Apple’s AVAudioSession reference.
You can either use the current_category property or the set_category() method for more control.
Properties¶
int |
|
Methods¶
int |
set_category(category: SessionCategory, mode: SessionMode, policy: RouteSharingPolicy, options: int) |
Enumerations¶
enum CategoryOptions: 🔗
CategoryOptions MIX_WITH_OTHERS = 1
Option to mix audio with other apps.
CategoryOptions DUCK_OTHERS = 2
Option to duck other apps’ audio.
CategoryOptions ALLOW_BLUETOOTH = 4
Option to allow Bluetooth output.
CategoryOptions DEFAULT_TO_SPEAKER = 8
Option to default audio to speaker.
CategoryOptions INTERRUPT_SPOKEN_AUDIO_AND_MIX_WITH_OTHERS = 17
Option to interrupt spoken audio and mix with others.
CategoryOptions ALLOW_BLUETOOTH_A2DP = 32
Option to allow Bluetooth A2DP.
CategoryOptions ALLOW_AIRPLAY = 64
Option to allow AirPlay.
CategoryOptions OVERRIDE_MUTED_MICROPHONE_INTERRUPTION = 128
Option to override muted microphone interruption.
enum RouteSharingPolicy: 🔗
RouteSharingPolicy ROUTE_SHARING_DEFAULT = 0
There is currently no description for this enum. Please help us by contributing one!
RouteSharingPolicy LONG_FORM_AUDIO = 1
Route sharing policy for long-form audio.
RouteSharingPolicy INDEPENDENT = 2
Independent route sharing policy.
RouteSharingPolicy LONG_FORM = 3
Alias for LONG_FORM_AUDIO.
enum SessionCategory: 🔗
SessionCategory AMBIENT = 0
Plays audio quietly and mixes with other apps, ideal for games that should respect background music.
SessionCategory MULTI_ROUTE = 1
Allows simultaneous input and output on multiple ports such as iPad USB headsets and speakers.
SessionCategory PLAY_AND_RECORD = 2
Enables full duplex audio for gameplay that records the microphone while playing effects.
SessionCategory PLAYBACK = 3
Optimised for playback only and silences system music while your game is active.
SessionCategory RECORD = 4
Recording-only mode for utilities that only capture audio.
SessionCategory SOLO_AMBIENT = 5
Similar to AMBIENT but pauses other audio sessions when your project starts.
SessionCategory UNKNOWN = 6
Default fallback when the platform does not expose audio sessions (macOS desktop).
enum SessionMode: 🔗
SessionMode DEFAULT = 0
The default audio session mode.
SessionMode GAME_CHAT = 1
Mode for game chat, optimizing for voice processing.
SessionMode MEASUREMENT = 2
Mode for audio measurement.
SessionMode MOVIE_PLAYBACK = 3
Mode for movie playback.
SessionMode SPOKEN_AUDIO = 4
Mode for spoken audio.
SessionMode VIDEO_CHAT = 5
Mode for video chat.
SessionMode VOICE_CHAT = 6
Mode for voice chat.
SessionMode VOICE_PROMPT = 7
Mode for voice prompts.
Property Descriptions¶
int current_category = 6 🔗
void set_current_category(value: int)
int get_current_category()
The current audio session category.
Method Descriptions¶
int set_category(category: SessionCategory, mode: SessionMode, policy: RouteSharingPolicy, options: int) 🔗
Sets the shared audio session category, mode, route sharing policy, and options.
category: The audio session category to set (e.g., PLAYBACK, RECORD).
mode: The audio session mode (e.g., DEFAULT, GAME_CHAT).
policy: The route sharing policy (e.g., ROUTE_SHARING_DEFAULT, LONG_FORM_AUDIO).
options: A bitmask of CategoryOptions values (e.g., AVAudioSession.MIX_WITH_OTHERS | AVAudioSession.DUCK_OTHERS).
Returns @GlobalScope.OK on success, or @GlobalScope.FAILED if the setting could not be applied (e.g. on macOS where this is not supported, or if an error occurs).