Prepares and plays multiple audio resources for synchronized playback at a specified time.
This method creates an `AudioPlaybackGroupController` that coordinates
playback across multiple entity/resource pairs. All audio sources in
the group will be synchronized to sample-accurate precision.
After the controller is created, the ``AudioPlaybackGroupController/play(at:)``
method of the controller that it returns is immediately called.
Any call to play() will cancel pending scheduled time and play audio immediately,
while any call to playAudio(at: AVAudioTime) will cancel current scheduled time
and schedule for new time.
To maintain precise timing, audio preparation must complete before the scheduled playback time.
If preparation is still in progress when the scheduled time arrives, or if the scheduled time is
in the past, playback will start immediately, which may result in timing drift.
The returned controller's ``AudioPlaybackGroupController/isPlaying`` property
becomes `true` immediately after this call returns. Code that checks `isPlaying`
to decide whether to trigger another action — such as starting a different sound —
reads the correct state without racing against the scheduled start time.
- Parameters:
- resourcesAndEntities: An array of tuples containing audio
resources and their associated entities. The same entity can appear
multiple times with different resources.
- time: The AVAudioTime when the audio file should start playing.
- Returns: An `AudioPlaybackGroupController` for the synchronized group.
- Throws: An error if the audio preparation fails.
## Usage Notes
- The same entity can be used with multiple resources in the same group
- Entities can participate in multiple groups simultaneously
- The completion handler fires when the longest resource finishes
Prepares and plays multiple audio resources for synchronized playback
This method creates an `AudioPlaybackGroupController` that coordinates
playback across multiple entity/resource pairs. All audio sources in
the group will be synchronized to sample-accurate precision.
After the controller is created, the ``AudioPlaybackGroupController/play()``
method of the controller that it returns is immediately called.
- Parameter resourcesAndEntities: An array of tuples containing audio
resources and their associated entities. The same entity can appear
multiple times with different resources.
- Returns: An `AudioPlaybackGroupController` for the synchronized group.
- Throws: An error if the audio preparation fails.
## Usage Notes
- The same entity can be used with multiple resources in the same group
- Entities can participate in multiple groups simultaneously
- The completion handler fires when the longest resource finishes
Prepares multiple audio resources for synchronized playback without starting them.
Use this method to set up a group of audio sources that you want to play together.
Each resource is paired with the entity that emits it. Call
``AudioPlaybackGroupController/play()`` or
``AudioPlaybackGroupController/play(at:)`` to begin playback.
- Parameter resourcesAndEntities: An array of tuples pairing each audio resource
with the entity that emits it. The same entity may appear multiple times with
different resources, and a single entity can participate in multiple groups.
- Returns: A controller that coordinates playback of the synchronized group.
- Throws: An error if audio preparation fails.
