@mustafaj/capacitor-plugin-playlist 0.9.0

package/dist/esm/interfaces.d.ts

@@ -0,0 +1,246 @@
+import { RmxAudioErrorType, RmxAudioStatusMessage } from './Constants';
+/**
+ * Callback function for the on(eventName) handlers
+ */
+export declare type AudioPlayerEventHandler = (args?: any) => void;
+/**
+ * @internal
+ * The collection of event handlers currently held by the plugin
+ */
+export interface AudioPlayerEventHandlers {
+    [key: string]: AudioPlayerEventHandler[];
+}
+export declare type PlaylistStatusChangeCallback = (data: PlaylistStatusChangeCallbackArg) => void;
+export interface PlaylistStatusChangeCallbackArg {
+    action: string;
+    status: OnStatusCallbackData;
+}
+export interface AudioTrackOptions {
+    playFromPosition: number;
+    startPaused: boolean;
+    retainPosition: boolean;
+    playFromId: string;
+}
+/**
+ * Options governing the overall behavior of the audio player plugin
+ */
+export interface AudioPlayerOptions {
+    /**
+     * Should the plugin's javascript dump the status message stream to the javascript console?
+     */
+    verbose?: boolean;
+    /**
+     * If true, when pausing a live stream, play will continue from the LIVE POSITION (e.g. the stream
+     * jumps forward to the current point in time, rather than picking up where it left off when you paused).
+     * If false, the stream will continue where you paused. The drawback of doing this is that when the audio
+     * buffer fills, it will jump forward to the current point in time, cause a disjoint in playback.
+     *
+     * Default is true.
+     */
+    resetStreamOnPause?: boolean;
+    /**
+     * Further options for notifications
+     */
+    options?: NotificationOptions;
+}
+export interface NotificationOptions {
+    icon?: string;
+}
+/**
+ * Options governing how the items are managed when using setPlaylistItems
+ * to update the playlist. This is typically useful if you are retaining items
+ * that were in the previous list.
+ */
+export interface PlaylistItemOptions {
+    /**
+     * If true, the plugin will continue playback from the current playback position after
+     * setting the items to the playlist.
+     */
+    retainPosition?: boolean;
+    /**
+     * If retainPosition is true, this value will tell the plugin the exact time to start from,
+     * rather than letting the plugin decide based on current playback.
+     */
+    playFromPosition?: number;
+    /**
+     * If retainPosition is true, this value will tell the plugin the uid of the "current" item to start from,
+     * rather than letting the plugin decide based on current playback.
+     */
+    playFromId?: string;
+    /**
+     * If playback should immediately begin when calling setPlaylistItems on the plugin.
+     * Default is false;
+     */
+    startPaused?: boolean;
+}
+/**
+ * An audio track for playback by the playlist.
+ */
+export interface AudioTrack {
+    /**
+     * This item is a streaming asset. Make sure this is set to true for stream URLs,
+     * otherwise you will get odd behavior when the asset is paused.
+     */
+    isStream?: boolean;
+    /**
+     * trackId is optional and if not passed in, an auto-generated UUID will be used.
+     */
+    trackId?: string;
+    /**
+     * URL of the asset; can be local, a URL, or a streaming URL.
+     * If the asset is a stream, make sure that isStream is set to true,
+     * otherwise the plugin can't properly handle the item's buffer.
+     */
+    assetUrl: string;
+    /**
+     * The local or remote URL to an image asset to be shown for this track.
+     * If this is null, the plugin's default image is used.
+     */
+    albumArt?: string;
+    /**
+     * The track's artist
+     */
+    artist: string;
+    /**
+     * Album the track belongs to
+     */
+    album: string;
+    /**
+     * Title of the track
+     */
+    title: string;
+}
+/**
+ * Encapsulates the fields you can pass to the plugin to remove a track.
+ * You can either remove a track by its ID if you know it, or by index if you know it;
+ * Index will be preferred if both index and ID are passed.
+ */
+export interface AudioTrackRemoval {
+    /**
+     * The track ID to remove
+     */
+    trackId?: string;
+    /**
+     * The index of a track to remove.
+     */
+    trackIndex?: number;
+}
+/**
+ * Encapsulates the data received by an onStatus callback
+ */
+export interface OnStatusCallbackData {
+    /**
+     * The ID of this track. If the track is null or has completed, this value is "NONE"
+     * If the playlist is completed, this value is "INVALID"
+     */
+    trackId: string;
+    /**
+     * The type of status update
+     */
+    msgType: RmxAudioStatusMessage;
+    /**
+     * The status payload. For all updates except ERROR, the data package is described by OnStatusCallbackUpdateData.
+     * For Errors, the data is shaped as OnStatusErrorCallbackData
+     */
+    value: OnStatusCallbackUpdateData | OnStatusTrackChangedData | OnStatusErrorCallbackData;
+}
+/**
+ * Reports information about the playlist state when a track changes.
+ * Includes the new track, its index, and the state of the playlist.
+ */
+export interface OnStatusTrackChangedData {
+    /**
+     * The new track that has been selected. May be null if you are at the end of the playlist,
+     * or the playlist has been emptied.
+     */
+    currentItem: AudioTrack;
+    /**
+     * The 0-based index of the new track. If the playlist has ended or been cleared, this will be -1.
+     */
+    currentIndex: number;
+    /**
+     * Indicates whether the playlist is now currently at the last item in the list.
+     */
+    isAtEnd: boolean;
+    /**
+     * Indicates whether the playlist is now at the first item in the list
+     */
+    isAtBeginning: boolean;
+    /**
+     * Indicates if there are additional playlist items after the current item.
+     */
+    hasNext: boolean;
+    /**
+     * Indicates if there are any items before this one in the playlist.
+     */
+    hasPrevious: boolean;
+}
+/**
+ * Contains the current track status as of the moment an onStatus update event is emitted.
+ */
+export interface OnStatusCallbackUpdateData {
+    /**
+     * The ID of this track corresponding to this event. If the track is null or has completed, this value is "NONE".
+     * This will happen when skipping to the beginning or end of the playlist.
+     * If the playlist is completed, this value is "INVALID"
+     */
+    trackId: string;
+    /**
+     * Boolean indicating whether this is a streaming track.
+     */
+    isStream: boolean;
+    /**
+     * The current index of the track in the playlist.
+     */
+    currentIndex: number;
+    /**
+     * The current status of the track, as a string. This is used
+     * to summarize the various event states that a track can be in; e.g. "playing" is true for any number
+     * of track statuses. The Javascript interface takes care of this for you; this field is here only for reference.
+     */
+    status: 'unknown' | 'ready' | 'error' | 'playing' | 'loading' | 'paused';
+    /**
+     * Current playback position of the reported track.
+     */
+    currentPosition: number;
+    /**
+     * The known duration of the reported track. For streams or malformed MP3's, this value will be 0.
+     */
+    duration: number;
+    /**
+     * Progress of track playback, as a percent, in the range 0 - 100
+     */
+    playbackPercent: number;
+    /**
+     * Buffering progress of the track, as a percent, in the range 0 - 100
+     */
+    bufferPercent: number;
+    /**
+     * The starting position of the buffering progress. For now, this is always reported as 0.
+     */
+    bufferStart: number;
+    /**
+     * The maximum position, in seconds, of the track buffer. For now, only the buffer with the maximum
+     * playback position is reported, even if there are other segments (due to seeking, for example).
+     * Practically speaking you don't need to worry about that, as in both implementations the
+     * minor gaps are automatically filled in by the underlying players.
+     */
+    bufferEnd: number;
+}
+/**
+ * Represents an error reported by the onStatus callback.
+ */
+export interface OnStatusErrorCallbackData {
+    /**
+     * Error code
+     */
+    code: RmxAudioErrorType;
+    /**
+     * The error, as a message
+     */
+    message: string;
+}
+/**
+ * Function declaration for onStatus event handlers
+ */
+export declare type OnStatusCallback = (info: OnStatusCallbackData) => void;

package/dist/esm/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/esm/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":""}

package/dist/esm/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { PlaylistPlugin } from './definitions';
+declare const Playlist: PlaylistPlugin;
+export { Playlist };

package/dist/esm/plugin.js

@@ -0,0 +1,13 @@
+import { registerPlugin } from '@capacitor/core';
+// todo: find out why we get imported twice
+let playListWebInstance;
+const Playlist = registerPlugin('Playlist', {
+    web: () => import('./web').then(m => {
+        if (!playListWebInstance) {
+            playListWebInstance = new m.PlaylistWeb();
+        }
+        return playListWebInstance;
+    }),
+});
+export { Playlist };
+//# sourceMappingURL=plugin.js.map

package/dist/esm/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAI/C,2CAA2C;AAC3C,IAAI,mBAAmC,CAAC;AACxC,MAAM,QAAQ,GAAG,cAAc,CAAiB,UAAU,EAAE;IACxD,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QAChC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACvB,mBAAmB,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9C,CAAC;QACD,OAAO,mBAAmB,CAAC;IAC/B,CAAC,CAAC;CACL,CAAC,CAAC;AACH,OAAO,EAAC,QAAQ,EAAC,CAAC"}

package/dist/esm/utils.d.ts

@@ -0,0 +1,15 @@
+import { AudioTrack } from './interfaces';
+/**
+ * Validates the list of AudioTrack items to ensure they are valid.
+ * Used internally but you can call this if you need to :)
+ *
+ * @param items The AudioTrack items to validate
+ */
+export declare const validateTracks: (items: AudioTrack[]) => AudioTrack[];
+/**
+ * Validate a single track and ensure it is valid for playback.
+ * Used internally but you can call this if you need to :)
+ *
+ * @param track The AudioTrack to validate
+ */
+export declare const validateTrack: (track: AudioTrack) => AudioTrack | null;

package/dist/esm/utils.js

@@ -0,0 +1,48 @@
+/**
+ * Validates the list of AudioTrack items to ensure they are valid.
+ * Used internally but you can call this if you need to :)
+ *
+ * @param items The AudioTrack items to validate
+ */
+export const validateTracks = (items) => {
+    if (!items || !Array.isArray(items)) {
+        return [];
+    }
+    return items.map(validateTrack).filter(x => !!x); // may produce an empty array!
+};
+/**
+ * Validate a single track and ensure it is valid for playback.
+ * Used internally but you can call this if you need to :)
+ *
+ * @param track The AudioTrack to validate
+ */
+export const validateTrack = (track) => {
+    if (!track) {
+        return null;
+    }
+    // For now we will rely on TS to do the heavy lifting, but we can add a validation here
+    // that all the required fields are valid. For now we just take care of the unique ID.
+    track.trackId = track.trackId || generateUUID();
+    return track;
+};
+/**
+ * Generate a v4 UUID for use as a unique trackId. Used internally, but you can use this to generate track ID's if you want.
+ */
+const generateUUID = () => {
+    var d = new Date().getTime();
+    if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
+        d += performance.now(); //use high-precision timer if available
+    }
+    // There are better ways to do this in ES6, we are intentionally avoiding the import
+    // of an ES6 polyfill here.
+    const template = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx';
+    return [].slice.call(template).map(function (c) {
+        if (c === '-' || c === '4') {
+            return c;
+        }
+        var r = (d + Math.random() * 16) % 16 | 0;
+        d = Math.floor(d / 16);
+        return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+    }).join('');
+};
+//# sourceMappingURL=utils.js.map

package/dist/esm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAmB,EAAE,EAAE;IAClD,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAiB,CAAC,CAAC,8BAA8B;AACpG,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAiB,EAAE,EAAE;IAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,uFAAuF;IACvF,sFAAsF;IACtF,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,YAAY,EAAE,CAAC;IAChD,OAAO,KAAK,CAAC;AACjB,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,YAAY,GAAG,GAAG,EAAE;IACtB,IAAI,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;IAC7B,IAAI,OAAO,WAAW,KAAK,WAAW,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAC9E,CAAC,IAAI,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,uCAAuC;IACnE,CAAC;IACD,oFAAoF;IACpF,2BAA2B;IAC3B,MAAM,QAAQ,GAAG,sCAAsC,CAAC;IACxD,OAAmB,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAE,CAAC,GAAG,CAAC,UAAS,CAAC;QACtD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACzB,OAAO,CAAC,CAAC;QACb,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC1C,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAChB,CAAC,CAAC"}

package/dist/esm/web.d.ts

@@ -0,0 +1,54 @@
+import { WebPlugin } from '@capacitor/core';
+import { RmxAudioStatusMessage } from './Constants';
+import { AddAllItemOptions, AddItemOptions, PlayByIdOptions, PlayByIndexOptions, PlaylistOptions, PlaylistPlugin, RemoveItemOptions, RemoveItemsOptions, SeekToOptions, SelectByIdOptions, SelectByIndexOptions, SetLoopOptions, SetPlaybackRateOptions, SetPlaybackVolumeOptions } from './definitions';
+import { AudioPlayerOptions, AudioTrack } from './interfaces';
+export declare class PlaylistWeb extends WebPlugin implements PlaylistPlugin {
+    protected audio: HTMLAudioElement | undefined;
+    protected playlistItems: AudioTrack[];
+    protected loop: boolean;
+    protected options: AudioPlayerOptions;
+    protected currentTrack: AudioTrack | null;
+    protected lastState: string;
+    addAllItems(options: AddAllItemOptions): Promise<void>;
+    addItem(options: AddItemOptions): Promise<void>;
+    clearAllItems(): Promise<void>;
+    getPlaylist(): Promise<{
+        items: AudioTrack[];
+    }>;
+    initialize(): Promise<void>;
+    pause(): Promise<void>;
+    play(): Promise<void>;
+    playTrackById(options: PlayByIdOptions): Promise<void>;
+    playTrackByIndex(options: PlayByIndexOptions): Promise<void>;
+    release(): Promise<void>;
+    create(): Promise<void>;
+    removeItem(options: RemoveItemOptions): Promise<void>;
+    removeItems(options: RemoveItemsOptions): Promise<void>;
+    seekTo(options: SeekToOptions): Promise<void>;
+    selectTrackById(options: SelectByIdOptions): Promise<void>;
+    selectTrackByIndex(options: SelectByIndexOptions): Promise<void>;
+    setLoop(options: SetLoopOptions): Promise<void>;
+    setOptions(options: AudioPlayerOptions): Promise<void>;
+    setPlaybackVolume(options: SetPlaybackVolumeOptions): Promise<void>;
+    setPlaylistItems(options: PlaylistOptions): Promise<void>;
+    skipForward(): Promise<void>;
+    skipBack(): Promise<void>;
+    setPlaybackRate(options: SetPlaybackRateOptions): Promise<void>;
+    setMediaSessionRemoteControlMetadata(): Promise<void>;
+    mediaSessionControlsHandler(actionDetails: MediaSessionActionDetails): Promise<void>;
+    registerHtmlListeners(position?: number): void;
+    protected getCurrentTrackId(): string | undefined;
+    protected getCurrentIndex(): number;
+    protected getCurrentTrackStatus(currentState: string): {
+        trackId: string | undefined;
+        isStream: boolean;
+        currentIndex: number;
+        status: string;
+        currentPosition: number;
+        duration: number;
+    };
+    protected setCurrent(item: AudioTrack, position?: number, forceAutoplay?: boolean): Promise<void>;
+    protected updateStatus(msgType: RmxAudioStatusMessage, value: any, trackId?: string): void;
+    private hlsLoaded;
+    protected loadHlsJs(): Promise<unknown>;
+}