ez-web-audio/dist/track.d.ts

Making the Web Audio API super EZ since 2024.

import { TimeObject } from './utils/create-time-object';
import { Sound } from './sound';
import { SeekType } from './controllers/base-param-controller';
/**
 * Music track with position tracking, pause/resume, and seeking.
 *
 * Track extends {@link Sound} with playback position awareness. Use Track for longer
 * audio files where users need to pause, resume, or seek to specific positions.
 * Each Track can only play once at a time (unlike Sound which allows overlap).
 *
 * @example
 * ```typescript
 * import { createTrack } from 'ez-web-audio'
 *
 * const track = await createTrack('song.mp3')
 * track.play()
 *
 * // Pause and resume
 * track.pause()
 * track.resume()
 *
 * // Seek to 30 seconds
 * track.seek(30).from('seconds')
 *
 * // Get current position
 * console.log(track.position)
 * // { raw: 30.5, string: '0:30', pojo: { minutes: 0, seconds: 30 } }
 *
 * // Check playback state
 * console.log(track.isPlaying)     // true
 * console.log(track.percentPlayed) // 15.5
 * ```
 */
export declare class Track extends Sound {
    /** Stores the requestAnimationFrame ID for position tracking cleanup. */
    private rafId;
    /**
     * Get the current playback position.
     *
     * Returns a TimeObject with the position in multiple formats:
     * - `raw`: Position in seconds
     * - `string`: Formatted as 'MM:SS'
     * - `pojo`: Object with `minutes` and `seconds` properties
     *
     * @example
     * ```typescript
     * const track = await createTrack('song.mp3')
     * track.play()
     *
     * // After playing for a while
     * console.log(track.position.raw)    // 65.5
     * console.log(track.position.string) // '1:05'
     * console.log(track.position.pojo)   // { minutes: 1, seconds: 5 }
     * ```
     */
    get position(): TimeObject;
    /**
     * Get the current playback position as a percentage (0-100).
     *
     * @example
     * ```typescript
     * const track = await createTrack('song.mp3')
     * track.play()
     *
     * // Use for progress bar
     * progressBar.style.width = `${track.percentPlayed}%`
     * ```
     */
    get percentPlayed(): number;
    /**
     * Hook called after playback starts.
     * Sets up the onended handler and starts position tracking.
     * @protected
     */
    protected _onPlaybackStarted(): void;
    /**
     * Pause playback at the current position.
     *
     * The track remembers its position so it can be resumed later.
     * Emits a 'pause' event with the current playback position.
     *
     * @example
     * ```typescript
     * const track = await createTrack('song.mp3')
     * track.play()
     *
     * // Pause after 5 seconds
     * setTimeout(() => track.pause(), 5000)
     *
     * // Listen for pause events
     * track.on('pause', (e) => {
     *   console.log('Paused at', e.detail.position)
     * })
     * ```
     */
    pause(): void;
    /**
     * Resume playback from the paused position.
     *
     * If the track was paused, resumes from where it left off.
     * Emits a 'resume' event with the playback position.
     *
     * @example
     * ```typescript
     * const track = await createTrack('song.mp3')
     * track.play()
     * track.pause()
     *
     * // Resume later
     * track.resume()
     *
     * // Listen for resume events
     * track.on('resume', (e) => {
     *   console.log('Resumed at', e.detail.position)
     * })
     * ```
     */
    resume(): void;
    /**
     * Stop playback and reset position to the beginning.
     *
     * Unlike pause(), stop() resets the playback position to 0.
     * The next play() will start from the beginning.
     *
     * @example
     * ```typescript
     * const track = await createTrack('song.mp3')
     * track.play()
     *
     * // Stop and reset
     * await track.stop()
     * console.log(track.position.raw) // 0
     * ```
     */
    stop(): Promise<void>;
    /**
     * Update startOffset using requestAnimationFrame for smooth position tracking.
     * Loop ends when playback stops or is paused.
     * @private
     */
    private trackPlayPosition;
    /**
     * Seek to a specific position in the track.
     *
     * Returns a fluent builder with `.from(type)` to specify the unit of the value:
     * - `'seconds'`: Absolute position in seconds
     * - `'percent'`: Percentage of total duration (0-100)
     * - `'ratio'`: Ratio of total duration (0-1)
     * - `'inverseRatio'`: Distance from end as ratio (0 = end, 1 = start)
     *
     * Emits a 'seek' event with the new and previous positions.
     *
     * @param amount - The position value (meaning depends on the `.from()` type)
     * @returns Fluent builder with `.from(type)` method
     *
     * @example
     * ```typescript
     * const track = await createTrack('song.mp3')
     *
     * // For a track with 100 second duration, all of these seek to 90 seconds:
     * track.seek(90).from('seconds')
     * track.seek(90).from('percent')
     * track.seek(0.9).from('ratio')
     * track.seek(0.1).from('inverseRatio')
     *
     * // Listen for seek events
     * track.on('seek', (e) => {
     *   console.log('Seeked from', e.detail.previousPosition, 'to', e.detail.position)
     * })
     * ```
     */
    seek(amount: number): {
        from: (type: SeekType) => void;
    };
}
export default Track;
//# sourceMappingURL=track.d.ts.map