docs: audio playback position reports

[LautaroPetaccio]

Documents the new audio playback position reports on the SDK7 Sounds page (creator/sdk7/3d-essentials/sounds.md).

What's new on the page

• Playback position reports section: the tickNumber, currentOffset and clipLength fields the renderer writes into AudioEvent while a clip plays, and why they're the only reliable way to know what the player is actually hearing (currentTime is a write-only seek, and a clip starts some milliseconds after the scene asks for it).
• Opt in to position reports: reportPlaybackPosition on AudioSource is required, otherwise no position is ever written and the playback callbacks never run. Explains why it's opt-in: a position report is written every time the playhead moves, far more often than a state change, and a scene can have many audio sources, so scenes only pay for it where they need it. Every code example creates its AudioSource with the flag set.
• Read the playback position: registerAudioPlaybackEntity(entity, callback) with its { report, sceneTime, offset } payload, plus getAudioPlayback() and removeAudioPlaybackEntity().
• Sync gameplay to the sound: why a report must be compared against the scene clock at the tick it was sampled, that sceneTime - offset is the moment the audible clip started rather than a lag, and getSceneTimeAtTick() for scenes that handle raw reports (it works for VideoEvent too).
• Accuracy caveat: currentOffset is the decoder's read position, not the moment sound leaves the speaker. Output latency adds tens of milliseconds that no field carries, roughly constant per device, so calibrate once if you need better than tick accuracy.
• Marked as requiring an SDK release that includes the feature and an explorer that implements it, so the fields stay undefined elsewhere.

Corrections to the existing audio events content

• An AudioSource clip only ever reaches MS_NONE, MS_ERROR, MS_LOADING, MS_READY and MS_PLAYING. MS_PAUSED, MS_BUFFERING and MS_SEEKING only occur on an AudioStream, and there's no pause for a clip: setting playing to false stops and rewinds it.
• timestamp is a monotonic counter the renderer increments per report, not a time value. The page previously described it as the time of the state change.
• The currentTime property bullet now says it's a seek command that the renderer never writes back.

Related work

• SDK: feat(ecs): expose renderer playback-position reports for audio js-sdk-toolchain#1624
• Protocol: feat: report playback position in AudioEvent protocol#488
• Unity explorer: feat(audio): report playback position in AudioEvent while playing unity-explorer#10123
• ADR-318: ADR-318: Audio playback position reports adr#324
• Test scene: feat: audio playback position reports test scene (89,-12) sdk7-test-scenes#99

Supersedes decentraland/documentation#609, which targeted the now-archived decentraland/documentation repo. The content has been converted from Hugo shortcodes to GitBook syntax and reconciled with the audio events content that already exists on this page.