Skip to main content

SoundProgressStateInfo

The SoundProgressStateInfo interface provides detailed progress information about a sound's playback. It is emitted with the PROGRESS event when progress tracking is enabled.

Try it​

Start the sound and watch the progress values arrive as PROGRESS events fire.

Loading sound...

Progress

00:00 / 00:00
Ratio: 0.0000%
// Get progress values
soundHub.getCurrentTime('bells-melody'); // 0.0s
soundHub.getDuration('bells-melody'); // 0.0s
soundHub.getProgress('bells-melody'); // 0.000
soundHub.getProgressPercentage('bells-melody'); // 0%
Try it: Play the bells melody sound and watch the progress values update in real time. getProgress() returns a ratio (0-1), getProgressPercentage() returns a percentage (0-100).
export interface SoundProgressStateInfo {
  currentTime: number; // Current playback position in seconds
  duration: number; // Total duration in seconds
  progress: number; // Progress as a ratio from 0 to 1
  percentage: number; // Progress as a percentage from 0 to 100
  remaining: number; // Remaining time in seconds
  soundId: string; // The sound ID
  instanceId?: string; // Instance ID for multi-instance sounds
}

Enabling Progress Tracking​

Progress tracking can be enabled when playing a sound using the trackProgress option.

const mySoundHub = new SoundHub();
await mySoundHub.loadSound('podcast', '/audio/podcast.mp3');

// Enable progress tracking when playing
mySoundHub.play('podcast', {
  trackProgress: true,
});

Getting Progress Directly​

You can also get progress information directly without events:

const mySoundHub = new SoundHub();
await mySoundHub.loadSound('song', '/audio/song.mp3');
mySoundHub.play('song', { trackProgress: true });

// Get progress as a ratio (0 to 1)
const progress = mySoundHub.getProgress('song');
console.log(`Progress: ${Math.round(progress * 100)}%`);

// Get progress as a percentage (0 to 100)
const percentage = mySoundHub.getProgressPercentage('song');
console.log(`Progress: ${percentage}%`);

// Get current playback position
const currentTime = mySoundHub.getCurrentTime('song');
console.log(`Current time: ${currentTime} seconds`);

// Get total duration
const duration = mySoundHub.getDuration('song');
console.log(`Duration: ${duration} seconds`);

Listening for Progress Events​

const mySoundHub = new SoundHub();
await mySoundHub.loadSound('lecture', '/audio/lecture.mp3');

mySoundHub.play('lecture', { trackProgress: true });

// Listen for progress updates
mySoundHub.addEventListener(SoundEventsEnum.PROGRESS, (event: SoundEvent) => {
  const info = event.progressInfo as SoundProgressStateInfo;
  
  if (info) {
    console.log(`Progress: ${info.percentage.toFixed(1)}%`);
    console.log(`Time: ${formatTime(info.currentTime)} / ${formatTime(info.duration)}`);
    console.log(`Remaining: ${formatTime(info.remaining)}`);
  }
});

function formatTime(seconds: number): string {
  const mins = Math.floor(seconds / 60);
  const secs = Math.floor(seconds % 60);
  return `${mins}:${secs.toString().padStart(2, '0')}`;
}

Controlling Progress Tracking​

const mySoundHub = new SoundHub();
await mySoundHub.loadSound('track', '/audio/track.mp3');

mySoundHub.play('track');

// Start tracking progress manually
mySoundHub.startProgressTracking('track');

// Change the update interval (global)
mySoundHub.setProgressUpdateInterval(100); // Update every 100ms

// Stop tracking progress
mySoundHub.stopProgressTracking('track');

Practical Example: Progress Bar​

const mySoundHub = new SoundHub();
await mySoundHub.loadSound('music', '/audio/music.mp3');

mySoundHub.play('music', { trackProgress: true });

mySoundHub.addEventListener(SoundEventsEnum.PROGRESS, (event: SoundEvent) => {
  const info = event.progressInfo as SoundProgressStateInfo;
  
  if (info) {
    const barWidth = 50;
    const filled = Math.round(info.progress * barWidth);
    const empty = barWidth - filled;
    const bar = '█'.repeat(filled) + '░'.repeat(empty);
    const timestamp = `${formatTime(info.currentTime)} / ${formatTime(info.duration)}`;
    
    console.log(`[${bar}] ${timestamp} (${info.percentage.toFixed(1)}%)`);
  }
});

function formatTime(seconds: number): string {
  const mins = Math.floor(seconds / 60);
  const secs = Math.floor(seconds % 60);
  return `${mins}:${secs.toString().padStart(2, '0')}`;
}