This repository was archived by the owner on Sep 21, 2026. It is now read-only.
Repository navigation
docs: audio playback position reports in audioEventsSystem - #609
Closed
LautaroPetaccio wants to merge 3 commits into
Closed
LautaroPetaccio wants to merge 3 commits into
LautaroPetaccio wants to merge 3 commits into
Conversation
Add an Audio events section to the SDK7 sounds page. It documents the existing audioEventsSystem API (registerAudioEventsEntity, getAudioState, MediaState) and the new playback position reports: the optional tickNumber, currentOffset and clipLength fields of AudioEvent, the registerAudioPlaybackEntity, removeAudioPlaybackEntity and getAudioPlayback functions, and the tickNumber correlation pattern for syncing gameplay to the sound that is actually heard. Flag that the feature needs an SDK release that includes it and an explorer that implements the reports, and note on the currentTime property that it is a write-only seek command.
Deploying documentation with
|
| Latest commit: |
8b9882e
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://d49a298f.new-docs-6m4.pages.dev |
| Branch Preview URL: | https://docs-audio-playback-position.new-docs-6m4.pages.dev |
This was referenced Sep 17, 2026
Open
LautaroPetaccio
marked this pull request as ready for review
September 17, 2026 13:43
LautaroPetaccio
requested review from
nearnshaw and
pravusjif
and removed request for
nearnshaw
September 17, 2026 14:29
mikhail-dcl
approved these changes
Sep 17, 2026
The renderer has no fixed reporting interval; it writes whenever the playhead moves. Drop the twice-a-second claim and describe delivery as it is: once per frame with the newest report. Replace the hand-written per-tick clock history with registerAudioPlaybackSampleEntity, which the SDK now provides, and mention getSceneTimeAtTick for scenes that want the raw reports. The old example asked every scene to rebuild the part that is easiest to get wrong. Add the caveat that current_offset is the decoder's position, so output latency sits on top of it and no property reports it.
The SDK collapsed the raw-report callback and the resolved one into a single registerAudioPlaybackEntity that hands over the resolved reading. Update both examples and drop the raw variant, which no longer exists.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documents the audio playback position reports that renderers write into the
AudioEventcomponent while anAudioSourceclip plays, and theaudioEventsSystemfunctions that expose them.Changes in
content/creator/sdk7/3d-essentials/sounds.md:audioEventsSystemat all, so it now documents the pre-existing API first (registerAudioEventsEntity,getAudioState,hasAudioEventsEntity,removeAudioEventsEntity,MediaState), including thattimestampis a per-entity counter and not a time.AudioEventfields (tickNumber,currentOffset,clipLength), theregisterAudioPlaybackEntity/removeAudioPlaybackEntity/getAudioPlaybackfunctions with short examples, why the reports are needed (renderer start delay,currentTimebeing a write-only seek), that state-change callbacks do not fire for position-only reports, graceful handling when no position has been reported, and typical uses.registerAudioPlaybackEntityhands over{ report, sceneTime, offset }already resolved;getSceneTimeAtTickis mentioned for scenes handling raw reports or video. Subtracting offset from scene time gives the moment the audible clip started, which is the value worth keeping.currentOffsetis the decoder's read position: the sound card and its buffers add a few tens of milliseconds that no property reports, roughly constant per device, so a scene needing better than tick accuracy should measure it once and subtract it.currentTimebullet now says it is a seek command the renderer never writes back to, and links to the new section.The contributor reference pages (
content/contributor/runtime/components.md,content/contributor/explorer-renderer/components/components.md) were checked and left untouched: neither listsAudioEventor its fields today.Caveat
This describes a feature that is not released yet. It needs an SDK release that includes the change and an explorer that implements the reports; the Unity explorer (DCL 2.0 desktop client) is the first. The page flags this with a note, and explains that on explorers without support the new fields stay
undefinedandgetAudioPlayback()returnsundefined. This PR should stay in draft until the SDK change ships.Related
Verification
Built locally with Hugo 0.108.0 (same version as CI); all
refshortcodes resolve and the new headings render.Related pull requests
scenes/89,-12-audio-playback-position): feat: audio playback position reports test scene (89,-12) sdk7-test-scenes#99