Skip to main content

Audio Focus Development Guide

Inside a vehicle, multiple sounds such as music, navigation, calls, and safety/emergency alerts can be played simultaneously or compete with each other. Which sound to play/stop/reject must be designed and implemented according to the policy below, based on AAOS Audio Focus, while strictly following the Pleos Connect Audio Focus Policy.

AAOS Audio Focus: Basic Concepts

The following explains the basic concepts and terminology of AAOS Audio Focus. In actual design and implementation, follow the subsequent Pleos Connect Audio Focus Policy.

Basic Focus Principles​

AAOS processes incoming requests based on predefined interactions between the request’s CarAudioContext and the CarAudioContext of the current focus holder(s).

Focus Interactions​

  • R(Reject): Rejection interaction. The new request is rejected and does not obtain focus.
  • E(Exclusive): Exclusive interaction. The new request gains focus and the existing holder loses focus.
  • C(Concurrent): Concurrent interaction. If conditions are met, both the existing holder and the new request retain focus concurrently. (Generally duck-based)
Important: Focus is not the only means of controlling the audio subsystem; it is a collision-prevention/indirect control mechanism.

Conditions for C(Concurrent) to Hold​

If concurrent playback is intended, the incoming request should use AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK (typically), and depending on the existing holder settings (for example, whether to pause while ducked), C may be broken.

Final Decision Rules When There Are Multiple Focus Holders​

Due to C, there can be multiple current holders. In this case, the new request compares the result against each holder and applies the most conservative outcome.

  • Priority: R > E > C

User Setting for Handling Navigation During Calls (Optional)​

AAOS may provide a user setting that changes navigation during a call from C to R, and this can be supported with a flag in your implementation.

Delayable Focus (Optional)​

If a non-transient request would be rejected as R by the interaction, AAOS can support a “delayed request.” (Build the requester to accept delayed)

Pleos Connect Audio Focus Policy​

The Pleos Connect audio focus policy follows the following Pleos Connect Interaction Matrix.

Pleos Connect Interaction Matrix v1.0 (2026-01-28)

Pleos Connect Interaction Matrix v1.0 (2026-01-28)

Legend
  • Row: Current focus holder’s context
  • Column: Incoming request’s context (Incoming Request’s CarAudioContext)
    • MUSIC, NAVIGATION, VOICE_COMMAND, CALL_RING, CALL, ALARM, NOTIFICATION, SYSTEM_SOUND, EMERGENCY, SAFETY, VEHICLE_STATUS, ANNOUNCEMENT
  • Cell value: E/C/R

Behavior Rules That Developers Must Implement​

Focus Request Rules (Using the Request API)​

  1. Each audio stream must request focus with AudioAttributes + AudioFocusRequest before playback starts.
  2. For contexts that expect C (for example, NAVIGATION concurrently with MUSIC), the request should in principle use AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK.
  3. For contexts that require E (for example, CALL, EMERGENCY, etc.), use an appropriate gain for the purpose, but do not attempt to hard-control everything solely through focus.

Handling Focus Change Events (Required)​

You must handle focus loss/gain events. Although handling focus change events is not mandatory in AAOS itself, it must be implemented to comply with automotive UX and policy.

  • AUDIOFOCUS_GAIN → Normal playback
  • AUDIOFOCUS_LOSS → Stop/terminate immediately
  • AUDIOFOCUS_LOSS_TRANSIENT → Pause with the possibility to resume
  • AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK → Apply ducking (volume attenuation)

Ducking (Attenuation) Implementation Rules​

  1. C generally implies duck-based coexistence.
  2. Targets of ducking (for example, MUSIC) must apply the following when receiving LOSS_TRANSIENT_CAN_DUCK.
    • Apply volume attenuation (for example, -X dB).
    • Restore volume when the duck-release condition is met (other stream ends/focus returned).
  3. If you configure the stream to pause while ducking, C may be broken, so configure/implement it according to the policy’s intent.

Handling Multi-holder Situations (Important)​

When multiple focus holders exist due to C, the final result for a new request must apply the most conservative outcome in the order of priority R > E > C. You must implement the following behavior:

  • Initialize result = C
  • For each currentHolder 
    cell = MATRIX[currentHolder][incoming]
    result = min_by_severity(result, cell) (R is the strongest)
  • Handle grant / steal / fail according to result.

Implementation Guide by Context​

EMERGENCY​

In EMERGENCY situations, implement the following behavior:

  • When EMERGENCY is the current context, most incoming requests are guaranteed as R (protecting emergency sounds).
  • Incoming EMERGENCY usually preempts the current context as E.
  • EMERGENCY-to-EMERGENCY is allowed as C (diagonal of the table) → In testing, make sure that music/notification requests fail during an emergency.

SAFETY​

In SAFETY situations, implement the following behavior:

  • SAFETY is generally guaranteed as C/E with MUSIC/NAVIGATION/notifications, etc.
  • If EMERGENCY is the current context, an incoming SAFETY must be R → The policy intent that Safety is below Emergency must be implemented clearly.

CALL / CALL_RING​

  • CALL must be implemented so that an incoming CALL to MUSIC is R (no music during a call) and an incoming CALL to NAVIGATION is C (navigation guidance allowed during a call).
  • However, if an option to reject navigation during a call is required, you may change NAVIGATION-in-CALL from C to R via a flag.

NAVIGATION ↔ MUSIC​

  • The two apps are primarily expected to coexist under C.
  • For actual coexistence, NAVIGATION must use a MAY_DUCK focus request.

Externalizing the Matrix into Code/Configuration​

To accommodate changes to the Pleos Connect audio focus policy, hard-coding is discouraged.

  • Recommendation: Package the matrix as interaction_matrix.json or CSV and load it at runtime.
  • Key: current_context, incoming_context → Value: E|C|R

Required Log/Debug Fields​

  • incoming context, gain type, client id
  • List of current holders
  • Per-holder matrix result (E/C/R)
  • Final result (R/E/C) and handling (grant/steal/reject)
  • Ducking apply/release events (target stream, attenuation value)

Verification Checklist​

After implementing audio focus, you must execute the following test scenarios.

  1. NAVIGATION request while MUSIC is playing → C (music duck + navigation playback)
  2. MUSIC request during CALL → R (request fails)
  3. CALL request during MUSIC → (current MUSIC row, CALL column = E) → The call preempts music.
  4. Any request (MUSIC/NOTIFICATION, etc.) during EMERGENCY playback → R
  5. VOICE_COMMAND request when there are two concurrent holders (MUSIC + NAVIGATION) under C
    • Check whether the final result is applied conservatively after comparing each individual result. (R/E take precedence)

Audio Contexts​

To simplify AAOS audio configuration, similar use cases are grouped into CarAudioContexts. These audio contexts are used throughout CarAudioService to define routing, volume groups, audio focus, and volume ducking management. The static audio contexts in AAOS are listed below.

This table describes the mapping between audio contexts and their use cases. Highlighted rows are provided for new system use cases.

CarAudioContextAttributeUsages
MUSICMUSIC, UNKNOWN, GAME, MEDIA
NAVIGATIONNAVIGATION, ASSISTANCE_NAVIGATION_GUIDANCE
VOICE_COMMANDVOICE_COMMAND, ASSISTANT
CALL_RINGCALL_RING, NOTIFICATION_RINGTONE
CALLCALL, VOICE_COMMUNICATION, VOICE_COMMUNICATION_SIGNALING
ALARMALARM
NOTIFICATIONNOTIFICATION, NOTIFICATION_*
SYSTEM_SOUNDSYSTEM_SOUND, ASSISTANCE_SONIFICATION, ASSISTANCE_ACCESSIBILITY
EMERGENCYEMERGENCY
SAFETYSAFETY
VEHICLE_STATUSVEHICLE_STATUS
ANNOUNCEMENTANNOUNCEMENT
info