@tidal-music/player/dist/index.d.ts

Player logic for TIDAL

import { CredentialsProvider } from '@tidal-music/common';
import { OutputDevice as OutputDevice_2 } from '../..';

export declare type ActiveDeviceModeChanged = CustomEvent<DeviceMode>;

export declare type ActiveDevicePassThroughChanged = CustomEvent<boolean>;

export declare type AssetPresentation = 'FULL' | 'PREVIEW';

export declare type AudioMode = 'DOLBY_ATMOS' | 'SONY_360RA' | 'STEREO';

export declare type AudioQuality = 'HI_RES' | 'HI_RES_LOSSLESS' | 'HIGH' | 'LOSSLESS' | 'LOW';

/**
 * Configure the module.
 *
 * @param {Options} options
 */
export declare function bootstrap(options: Options): void;

export declare type Codec = 'aac' | 'flac' | 'mp3';

declare type CommonErrorIds = 'EUnexpected';

export declare type DeviceChange = CustomEvent<DeviceChangePayload>;

declare type DeviceChangePayload = {
    devices: Array<OutputDevice>;
};

export declare type DeviceMode = 'exclusive' | 'shared';

export declare type EndedEvent = CustomEvent<{
    mediaProduct: MediaProduct;
    reason: EndReason;
}>;

declare type EndReason = 'completed' | 'error' | 'skip';

declare type Error_2 = {
    errorCode: ErrorCodes;
    errorId: ErrorIds;
    referenceId?: string;
};
export { Error_2 as Error }

export declare type ErrorCodes = NativePlayerDeviceErrorCodes | NativePlayerNetworkErrorCodes | NativePlayerOfflineErrorCodes | PlayerErrorCodes | ShakaDrmErrorCodes | ShakaManifestErrorCodes | ShakaMediaErrorCodes | ShakaNetworkErrorCodes | ShakaPlayerErrorCodes;

declare type ErrorIds = CommonErrorIds | OfflineErrorIds | PlaybackEngineErrorIds;

export declare const events: PlayerEventTarget;

/**
 * Get the asset position of the current playback session.
 * Defaults to 0 if nothing is playing.
 *
 * @returns {number}
 */
export declare function getAssetPosition(): number;

/**
 * Get the value for loudness normalization.
 *
 * @returns {LoudnessNormalizationMode}
 */
export declare function getLoudnessNormalizationMode(): LoudnessNormalizationMode;

/**
 * Get the media element with playback currently.
 *
 * @returns {HTMLMediaElement | null}
 */
export declare function getMediaElement(): HTMLMediaElement | null;

/**
 * Gets the currently active media product. This is the same value as
 * was included in the last sent MediaProductTransition event. If nothing
 * is loaded in the player yet or if the player was reset, null will be
 * returned.
 *
 * @returns {MediaProduct | null}
 */
export declare function getMediaProduct(): MediaProduct | null;

/**
 * Gets the next media product. This is the same value as
 * was included in the last successful call to setNext.
 *
 * Gets unset to return null on media-product-transition and
 * on player resets.
 *
 * @returns {MediaProduct | null}
 */
export declare function getNextMediaProduct(): MediaProduct | null;

/**
 * Get the available output devices.
 *
 * @returns { Set<OutputDevice>}
 */
export declare function getOutputDevices(): Promise<OutputDevice_2[]>;

/**
 * Gets the currently active playback context. This is the same value
 * as was included in the last sent MediaProductTransition event. If nothing
 * is loaded in the player yet or if the player was reset, undefined will be
 * returned.
 *
 * @returns {PlaybackContext | undefined}
 */
export declare function getPlaybackContext(): PlaybackContext | undefined;

/**
 * Get the current playback state of the active player.
 *
 * @returns {PlaybackState}
 */
export declare function getPlaybackState(): PlaybackState;

/**
 * Get the module version of the Player SDK.
 */
export declare function getPlayerVersion(): string;

/**
 * Get configured audio quality for streaming over WiFI.
 *
 * @returns {AudioQuality}
 */
export declare function getStreamingWifiAudioQuality(): AudioQuality;

/**
 * Gets current volume level.
 *
 * @returns {number}
 */
export declare function getVolumeLevel(): number;

/**
 * Will reset TIDAL Player from any current state and immediately make a
 * transition to the provided media product.
 *
 * Playback state will immediately change to NOT_PLAYING.
 *
 * @param {MediaProduct} mediaProduct - The media product to load.
 * @param {number} assetPosition - At which time in seconds playback should start when later calling the play method, defaults to 0.
 * @param {boolean} prefetch - Wether or not this is a prefetch. This should be set to true if you need a media product transition to boot the UI.
 *
 * @see {@link import('../../api/event/playback-state-change').PlaybackStateChange}
 *
 * @returns {Promise<void>} - On resolve, the requested media product is considered the active one and a MediaProductTransition will have been sent.
 */
export declare function load(mediaProduct: MediaProduct, assetPosition?: number, prefetch?: boolean): Promise<void>;

export declare type LoudnessNormalizationMode = 'ALBUM' | 'NONE' | 'TRACK';

/**
 * Contains information about a TIDAL media product.
 */
export declare type MediaProduct = {
    /** Optional extra attributes of the media product. Passed through to corresponding PlayLog event */
    extras?: Record<string, unknown>;
    /** The id of the product to play */
    productId: string;
    /** The type of the product to play */
    productType: 'demo' | 'track' | 'video';
    /** Optional client-set reference id to handle duplicated in a play queue implementation */
    referenceId?: string;
    /** The id of the source to play, passed along for event tracking */
    sourceId: string;
    /** The type of the source to play, passed along for event tracking */
    sourceType: string;
};

export declare type MediaProductTransition = CustomEvent<MediaProductTransitionPayload>;

/**
 * Playback engine has recently made a transition to requested mediaProduct X.
 *
 * Implicit media product transitions can be assumed to occur exactly when this event is sent.
 *
 * Information about the active playback session is given in playbackContext.
 */
declare type MediaProductTransitionPayload = {
    mediaProduct: MediaProduct;
    playbackContext: PlaybackContext;
};

declare type NativePlayerDeviceErrorCodes = 'NPD00' | 'NPD01' | 'NPD02' | 'NPD03' | 'NPD04' | 'NPD05';

declare type NativePlayerNetworkErrorCodes = 'NPN01';

declare type NativePlayerOfflineErrorCodes = 'NPO01' | 'NPO02' | 'NPO03';

declare type OfflineErrorIds = 'OEContentNotAvailableForSubscription' | 'OEContentNotAvailableInLocation' | 'OENetwork' | 'OENotAllowed' | 'OEOffliningNotAllowedOnDevice' | 'OERetryable';

declare type Options = {
    outputDevices: boolean;
    players: Array<PlayerConfig>;
};

export declare class OutputDevice {
    controllableVolume: boolean;
    id: string;
    name: string;
    nativeDeviceId?: string;
    type: OutputType | undefined;
    webDeviceId?: string;
    constructor({ controllableVolume, name, nativeDeviceId, type, webDeviceId, }: {
        controllableVolume?: boolean;
        name: string;
        nativeDeviceId?: string;
        type: OutputType | undefined;
        webDeviceId?: string;
    });
}

declare type OutputType = 'airplay' | 'bluetooth' | 'builtIn' | 'displayPort' | 'hdmi' | 'systemDefault' | 'usb' | 'windowsCommunication';

/**
 * Pause playback of active media product in the active player.
 *
 * Playback will pause and state transition to NOT_PLAYING.
 *
 * @see {@link import('../../api/event/playback-state-change').PlaybackStateChange}
 */
export declare function pause(): void | undefined;

/**
 * Start playback of active media product.
 *
 * Playback will start and state transition to PLAYING.
 *
 * If there is no media product previously loaded with
 * the load method, this method will do nothing.
 *
 * @returns {Promise<void>}
 * @see {@link import('../../api/event/playback-state-change').PlaybackStateChange}
 */
export declare function play(): Promise<void>;

/**
 * Contains playback related information for active media product.
 */
export declare type PlaybackContext = {
    actualAssetPresentation: AssetPresentation;
    actualAudioMode: AudioMode | null;
    actualAudioQuality: AudioQuality | null;
    actualDuration: number;
    actualProductId: string;
    actualStreamType: StreamType | null;
    actualVideoQuality: VideoQuality | null;
    assetPosition: number;
    bitDepth: null | number;
    codec: Codec | null;
    playbackSessionId: string;
    sampleRate: null | number;
};

declare type PlaybackEngineErrorIds = 'PEContentNotAvailableForSubscription' | 'PEContentNotAvailableInLocation' | 'PEMonthlyStreamQuotaExceeded' | 'PENetwork' | 'PENotAllowed' | 'PERetryable';

/**
 * IDLE: TIDAL Player has no active media product and nothing
 * set as next. This is the “default” state, nothing is happening
 * and nothing is scheduled to happen. This is the state which
 * TIDAL Player boots into, it is also the state reached after the
 * last requested media product finishes playing or after call to reset().
 *
 * PLAYING: TIDAL Player is currently playing the active media product.
 *
 * NOT_PLAYING: TIDAL Player has an active media product, but it is
 * currently not trying to play it. This can be due to the user having
 * pressed pause, some error occurred etc.
 *
 * STALLED: Playback is currently stalled due to some unexpected/unwanted
 * reason but TIDAL Player is still trying to play. E.g. buffering,
 * device resource issues etc. If TIDAL Player manages to resume playback
 * by itself, state will change to PLAYING. If TIDAL Player fails to
 * resume playback, state will change to NOT_PLAYING and a descriptive
 * UserMessage will be sent.
 */
export declare type PlaybackState = 'IDLE' | 'NOT_PLAYING' | 'PLAYING' | 'STALLED';

export declare type PlaybackStateChange = CustomEvent<PlaybackStateChangePayload>;

declare type PlaybackStateChangePayload = {
    state: PlaybackState;
};

declare type PlayerConfig = {
    itemTypes: Array<MediaProduct['productType']>;
    player: 'browser' | 'native' | 'shaka';
    qualities?: Array<AudioQuality>;
};

declare class PlayerError extends Error {
    errorCode: ErrorCodes | null;
    errorId: ErrorIds | null;
    referenceId: string | undefined;
    constructor(errorId: ErrorIds, errorCode: ErrorCodes, referenceId?: string);
    toJSON(): {
        errorCode: ErrorCodes | null;
        errorId: ErrorIds | null;
        referenceId: string | undefined;
    };
    toString(): string;
}

declare type PlayerErrorCodes = 'B9999' | 'NPBI0';

declare class PlayerEventTarget extends EventTarget {
    dispatchError(error: PlayerError): void;
}

/**
 * Gracefully reset to a clean initial state. Stops playback, removes any
 * setNext:ed items and makes sure each sub-player is reset also.
 *
 * Playback state will immediately change to IDLE.
 *
 * @returns {Promise<void>}
 * @see {@link import('../../api/event/playback-state-change').PlaybackStateChange}
 */
export declare function reset(): Promise<void>;

/**
 * Perform a seek on the active player.
 *
 * @param {number} time - seconds
 */
export declare function seek(time: number): Promise<number | void | undefined>;

/**
 * Configure the module to use another URL for the API than the normal one.
 *
 * @param {string} apiUrl
 */
export declare function setApiUrl(apiUrl: string): void;

/**
 * Tells TIDAL Player which string to use for the version key in event tracking.
 *
 * Must be called when bootstrapping TIDAL Player.
 *
 * @param {string} appVersion
 */
export declare function setAppVersion(appVersion: string): void;

/**
 * Tells TIDAL Player which client platform Player is running on. Used for streaming metrics.
 *
 * Must be called when bootstrapping TIDAL Player.
 *
 * @param {string} clientPlatform
 */
export declare function setClientPlatform(clientPlatform: string): void;

/**
 * Set the credentials provider TIDAL Player SDK should use for getting
 * session information
 *
 * @param {CredentialsProvider} newCredentialsProvider
 */
export declare function setCredentialsProvider(newCredentialsProvider: CredentialsProvider): void;

/**
 * What endpoint the module should send events to.
 *
 * @param {string} eventUrl
 */
export declare function setEventUrl(eventUrl: string): void;

/**
 * Set loudness normalization mode.
 *
 * @param {LoudnessNormalizationMode} mode
 */
export declare function setLoudnessNormalizationMode(mode: LoudnessNormalizationMode): void;

/**
 * Tell TIDAL Player to make an implicit transition to the selected media product
 * once the currently active product finishes playing. Can also be used to prepare
 * a media product for playback. Calling with mediaProduct set to undefined triggers
 * an unset of the previously setNext call.
 *
 * @param {MediaProduct | undefined} mediaProduct
 * @param {Array<string>} sessionTags
 */
export declare function setNext(mediaProduct?: MediaProduct, sessionTags?: Array<string>): Promise<void>;

/**
 * Set the output device. Applies to each sub-player that supports
 * output devices. Currently shaka and native.
 *
 * @param {string} sinkId - The sinkId we want to use as output.
 * @returns {Promise<string>} - The sinkId we are now using as output.
 */
export declare function setOutputDevice(sinkId: string): Promise<string>;

/**
 * Set device mode. Only available for native player.
 *
 * @param {NativePlayerDeviceMode} mode - The desired mode.
 * @returns {Promise<NativePlayerDeviceMode>} - The mode we now use.
 */
export declare function setOutputDeviceMode(mode?: DeviceMode): Promise<DeviceMode>;

/**
 * Set the AudioQuality to use when streaming over WiFi.
 *
 * @param {AudioQuality} streamingWifiAudioQuality
 */
export declare function setStreamingWifiAudioQuality(streamingWifiAudioQuality: AudioQuality): void;

/**
 * Set the desired volume level. Range 0-100. This level will be used for all players,
 * but when loudness normalization is active it will be adjusted inside the player.
 *
 * @param {number} desiredVolumeLevel
 */
export declare function setVolumeLevel(desiredVolumeLevel: number): void;

declare type ShakaDrmErrorCodes = 'S6000' | 'S6001' | 'S6002' | 'S6003' | 'S6004' | 'S6005' | 'S6006' | 'S6007' | 'S6008' | 'S6009' | 'S6010' | 'S6011' | 'S6012' | 'S6013' | 'S6014' | 'S6015' | 'S6016' | 'S6017';

declare type ShakaManifestErrorCodes = 'S4000' | 'S4001' | 'S4002' | 'S4003' | 'S4004' | 'S4005' | 'S4006' | 'S4007' | 'S4008' | 'S4009' | 'S4010' | 'S4011' | 'S4012' | 'S4013' | 'S4014' | 'S4015' | 'S4016' | 'S4017' | 'S4018' | 'S4019' | 'S4020' | 'S4021' | 'S4022' | 'S4023' | 'S4024' | 'S4025' | 'S4026' | 'S4027' | 'S4028' | 'S4029' | 'S4030' | 'S4031' | 'S4032' | 'S4033' | 'S4034' | 'S4035' | 'S4036' | 'S4037' | 'S4038' | 'S4039' | 'S4040' | 'S4041' | 'S4042' | 'S4043' | 'S4044';

declare type ShakaMediaErrorCodes = 'S3000' | 'S3001' | 'S3002' | 'S3003' | 'S3004' | 'S3005' | 'S3006' | 'S3007' | 'S3008' | 'S3009' | 'S3010' | 'S3011' | 'S3012' | 'S3013' | 'S3014' | 'S3015' | 'S3016' | 'S3017' | 'S3018' | 'S3019';

declare type ShakaNetworkErrorCodes = 'S1000' | 'S1001' | 'S1002' | 'S1003' | 'S1004' | 'S1005' | 'S1006' | 'S1007' | 'S1008' | 'S1009' | 'S1010' | 'S1011';

declare type ShakaPlayerErrorCodes = 'S7000' | 'S7001' | 'S7002' | 'S7003' | 'S7004';

/**
 * Start native player before playback to access output devices.
 */
export declare function startNativePlayer(): Promise<void>;

export declare type StreamingPrivilegesRevokedEvent = CustomEvent<string>;

export declare type StreamType = 'LIVE' | 'ON_DEMAND';

export declare type VideoQuality = 'AUDIO_ONLY' | 'HIGH' | 'LOW' | 'MEDIUM';

export { }