utils/timedCueTracks.js

/**
 * Normalize timed cue tracks from jsmediatags ID3 SYLT or WebM WEBVTT results
 * into a shared shape for captions / lipsync / events.
 *
 * @module platypus/utils/timedCueTracks
 */

/**
 * @typedef {Object} TimedCue
 * @property {string} text
 * @property {number} timeStamp
 * @property {number} [end]
 */

/**
 * @typedef {Object} TimedCueTrack
 * @property {string} descriptor shortText / track name (captions, lipsync, events, …)
 * @property {string} [contentType] ID3 content type or WebM kind (lowercase)
 * @property {string} [language]
 * @property {Array.<TimedCue>} synchronisedText
 */

/**
 * @param {Object} [tagResult] jsmediatags onSuccess payload
 * @return {Array.<TimedCueTrack>}
 */
export const getTimedCueTracks = (tagResult) => {
    if (!tagResult?.tags) {
        return [];
    }

    const
        {type, tags} = tagResult;

    if (type === 'WebM' || tags.WEBVTT) {
        const
            raw = tags.WEBVTT,
            list = raw == null ? [] : (Array.isArray(raw) ? raw : [raw]);

        return list.map((frame) => {
            const
                data = frame?.data ?? frame;

            return {
                descriptor: data.name || frame?.description || '',
                contentType: String(data.kind || '').toLowerCase(),
                language: data.language,
                synchronisedText: (data.cues || []).map(({text, timeStamp, end}) => ({
                    text,
                    timeStamp,
                    end
                }))
            };
        }).filter((track) => track.synchronisedText.length);
    }

    const
        SYLT = tags.SYLT;

    if (!SYLT) {
        return [];
    }

    const
        list = Array.isArray(SYLT) ? SYLT : [SYLT];

    return list.map(({data}) => ({
        descriptor: data?.descriptor || '',
        contentType: data?.contentType,
        language: data?.language,
        synchronisedText: data?.synchronisedText || []
    })).filter((track) => track.synchronisedText.length);
};

/**
 * Prefer captions descriptor, then transcription/lyrics content types (ID3 fallbacks).
 * @param {Array.<TimedCueTrack>} tracks
 * @return {?TimedCueTrack}
 */
export const findCaptionsTrack = (tracks) => {
    if (!tracks?.length) {
        return null;
    }

    return tracks.find(({descriptor}) => descriptor === 'captions' || descriptor === 'words')
        ?? tracks.find(({contentType}) => contentType === 'transcription' || contentType === 'captions')
        ?? tracks.find(({contentType}) => contentType === 'lyrics' || contentType === 'subtitles')
        ?? null;
};