Implement proper playback on audio components using Timer

[waynemwashuma]

Objective

Implements the audio playback system to use the centralized Timer component instead of the defunct custom playback property within audio components.

Note

This aligns the audio playback system with the engine's timing model, making audio playback control more intuitive and feature-rich. The changes enable sophisticated audio sequencing and synchronization with other timed events in the application.

New features available:

• Playback control: Control playback state with play, pause, stop and start.
• Playback speed: Control playback rate with timer.speed
• Precise seeking: Jump to specific positions with timer.seek()
• Cycle tracking: Use timer.cyclesCompleted() for loop counting
• State changes: Detect playback changes with timer.playbackChanged()

Solution

The solution involved replacing the internal playback state in AudioPlayer and AudioOscillator components with the standard Timer component used throughout the engine. This provides several benefits:

• Consistency: Uses the same timing system as other parts of the engine
• Better Control: Leverages existing timer functionality (play, pause, seek, speed control)
• Synchronization: Fixes issues where audio playback wouldn't properly sync with timer states

Key changes made:

• Removed internal playback property from audio components
• Added Timer component requirement for all audio entities
• Implemented proper audio node recreation when playback state changes

Showcase

Set up simple audio playback with timer control:

commands.spawn()
  .insertPrefab([
    new AudioPlayer({
      audio: server.load(Audio, 'assets/audio/music.m4a')
    }),
    new Timer({
      mode: TimerMode.Repeat
    })
  ])
  .build()

Control playback using timer methods

const query = new Query(world,[AudioPlayer,Timer])
const [player, timer] = query.get(audioEntity)

timer.pause().    // Pause playback
timer.play()      // Resume playback  
timer.seek(100)   // Seek to 100 seconds
timer.speed = 1.5 // Increase playback speed by 50%
timer.stop()      // Stop playback completely
timer.start()     // Start playback from beginning

The new audio playback demo also demonstrates various controls.

Migration Guide

This introduces breaking changes to audio component usage:

• For AudioPlayer:

// before
commands.spawn()
  .insertPrefab([
    new AudioPlayer({
      audio: server.load(Audio, 'assets/audio/music.m4a'),
      playbackMode: TimerMode.Repeat
    })
  ])
  .build()

// after
commands.spawn()
  .insertPrefab([
    new AudioPlayer({
      audio: server.load(Audio, 'assets/audio/music.m4a')
    }),
    new Timer({
      mode: TimerMode.Repeat
    })
  ])
  .build()

• For AudioOscillator:

// before
commands.spawn()
  .insertPrefab([
    new AudioOscillator({
      type: AudioOscillatorType.Sine,
      frequency: 440
    })
  ])
  .build()

// after
commands.spawn()
  .insertPrefab([
    new AudioOscillator({
      type: AudioOscillatorType.Sine,
      frequency: 440
    }),
    new Timer({
      mode: TimerMode.Repeat
    })
  ])
  .build()

Required Changes:

• Add Timer component to all entities containing audio components
• Remove playbackMode parameter from AudioPlayer constructor
• Update audio control code to use timer methods instead of internal playback state
• Audio playback now requires both audio component and timer component to function

Checklist

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.