tiny-essentials 1.28.4 → 1.28.6

package/dist/v1/libs/TinyMediaPlayer/SoundCloud.d.mts

@@ -0,0 +1,300 @@
+/**
+ * @typedef {import('../../basics/mediaContent.mjs').PictureDataType} PictureDataType
+ * @typedef {import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
+ * @typedef {import('./index.mjs').ContentTimeData} ContentTimeData
+ * @typedef {import('./index.mjs').ContentData} ContentData
+ *
+ * @typedef {import('./docs/SoundCloudWidget.mjs').SoundObject} SoundObject
+ * @typedef {import('./docs/SoundCloudWidget.mjs').MediaObject} MediaObject
+ * @typedef {import('./docs/SoundCloudWidget.mjs').TranscodingObject} TranscodingObject
+ * @typedef {import('./docs/SoundCloudWidget.mjs').PublisherObject} PublisherObject
+ * @typedef {import('./docs/SoundCloudWidget.mjs').UserBadgesObject} UserBadgesObject
+ * @typedef {import('./docs/SoundCloudWidget.mjs').CreatorSubscriptionObject} CreatorSubscriptionObject
+ * @typedef {import('./docs/SoundCloudWidget.mjs').VisualsObject} VisualsObject
+ * @typedef {import('./docs/SoundCloudWidget.mjs').VisualsObjectData} VisualsObjectData
+ * @typedef {import('./docs/SoundCloudWidget.mjs').UserObject} UserObject
+ */
+export type PictureDataType = import('../../basics/mediaContent.mjs').PictureDataType;
+export type MediaContent = import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>;
+export type ContentTimeData = import('./index.mjs').ContentTimeData;
+export type ContentData = import('./index.mjs').ContentData;
+export type SoundObject = import('./docs/SoundCloudWidget.mjs').SoundObject;
+export type MediaObject = import('./docs/SoundCloudWidget.mjs').MediaObject;
+export type TranscodingObject = import('./docs/SoundCloudWidget.mjs').TranscodingObject;
+export type PublisherObject = import('./docs/SoundCloudWidget.mjs').PublisherObject;
+export type UserBadgesObject = import('./docs/SoundCloudWidget.mjs').UserBadgesObject;
+export type CreatorSubscriptionObject = import('./docs/SoundCloudWidget.mjs').CreatorSubscriptionObject;
+export type VisualsObject = import('./docs/SoundCloudWidget.mjs').VisualsObject;
+export type VisualsObjectData = import('./docs/SoundCloudWidget.mjs').VisualsObjectData;
+export type UserObject = import('./docs/SoundCloudWidget.mjs').UserObject;
+export type HandlerFunc = (...args: any[]) => boolean;
+export type IframeContainerOptions = {
+    /**
+     * - The SoundCloud song ID to be loaded.
+     */
+    videoId: string;
+    /**
+     * - The iframe width in pixels or a string (e.g., '100%').
+     */
+    width?: number | string;
+    /**
+     * - The iframe height in pixels or a string (e.g., '100%').
+     */
+    height?: number | string;
+    /**
+     * - If true, the iframe will be invisible (opacity 0) and will not respond to clicks (pointer-events none) and appends it to the document body.
+     */
+    hidden?: boolean;
+    /**
+     * - If true, the video will start automatically upon loading.
+     */
+    autoPlay?: boolean;
+    /**
+     * - The track number to start playback from.
+     */
+    startTrack?: null | number;
+    /**
+     * - The color of the widget's user interface.
+     */
+    color?: string | null;
+    /**
+     * - Whether the "Buy" button is displayed in the widget.
+     */
+    buying?: boolean;
+    /**
+     * - Whether the "Share" button is displayed in the widget.
+     */
+    sharing?: boolean;
+    /**
+     * - Whether the "Download" button is displayed in the widget.
+     */
+    download?: boolean;
+    /**
+     * - Whether the track's artwork is displayed.
+     */
+    showArtwork?: boolean;
+    /**
+     * - Whether the play count is displayed.
+     */
+    showPlayCount?: boolean;
+    /**
+     * - Whether the user/artist information is displayed.
+     */
+    showUser?: boolean;
+    /**
+     * - Whether to restrict playback to a single active track.
+     */
+    singleActive?: boolean;
+};
+import SoundCloudWidget from './docs/SoundCloudWidget.mjs';
+import { BaseMediaAdapter } from './index.mjs';
+/**
+ * Method to ensure the SoundCloud Widget API script is loaded.
+ */
+declare const loadSoundCloudApi: () => Promise<any>;
+/**
+ * Returns a deep clone of the current YouTube player state values.
+ * This ensures the returned object is a copy and does not maintain a reference to the original state.
+ * @returns {Record<string, string>} A copy of the Events object.
+ */
+declare const getEventValues: () => Record<string, string>;
+/**
+ * Returns the SoundCloud Widget constructor from the global window object.
+ * @returns {typeof SoundCloudWidget} The SoundCloud Widget constructor.
+ * @throws {Error} If the SoundCloud API is not detected in the global scope.
+ */
+declare const getSCWidget: () => typeof SoundCloudWidget;
+/**
+ * Implementation of BaseMediaAdapter for the SoundCloud Widget API.
+ * This adapter manages the lifecycle of a SoundCloud widget embedded in a container.
+ * @extends BaseMediaAdapter
+ */
+declare class SoundCloudMediaAdapter extends BaseMediaAdapter {
+    #private;
+    /**
+     * Mapping SoundCloud API events for internal adapter events.
+     * @type {Record<string, string>}
+     * @private
+     */
+    private static EVENT_MAPPING;
+    /**
+     * Static object containing event names to match SC.Widget.Events.
+     * @type {Record<string, string>}
+     */
+    static Events: Record<string, string>;
+    /**
+     * Safety lock: If true, multiple instances can share the same player/iframe via WeakMap.
+     * If false, only one instance can be bound to a specific container at a time.
+     * @type {boolean}
+     */
+    static allowInstanceSharing: boolean;
+    /**
+     * Gets the globally configured default container for SoundCloud players.
+     * @returns {HTMLIFrameElement|null}
+     */
+    static get defaultContainer(): HTMLIFrameElement | null;
+    /**
+     * Sets the globally configured default container for SoundCloud players.
+     * @param {HTMLIFrameElement|null} element - The element to be used as the default container.
+     * @throws {TypeError} If the provided element is not an instance of HTMLIFrameElement.
+     */
+    static set defaultContainer(element: HTMLIFrameElement | null);
+    /**
+     * Creates a SoundCloud iframe element.
+     * This element can be used as the `defaultContainer` for the adapter.
+     *
+     * @param {IframeContainerOptions} options - Configuration for the iframe creation.
+     * @returns {HTMLIFrameElement} The created iframe element.
+     * @throws {TypeError} If the `videoId` is not a valid string.
+     */
+    static createIframeContainer(options: IframeContainerOptions): HTMLIFrameElement;
+    /**
+     * Returns the thumbnail URL for the currently loaded track.
+     * @param {string} trackId - The SoundCloud track ID.
+     * @returns {string} The thumbnail URL.
+     * @throws {TypeError} If the trackId is not a valid string.
+     */
+    static getThumbnailUrl(trackId: string): string;
+    get id(): string;
+    get loadedProgress(): number;
+    get currentContentId(): string | null;
+    /**
+     * Gets whether the adapter has been destroyed.
+     * @returns {boolean}
+     */
+    get destroyed(): boolean;
+    /**
+     * Initializes the SoundCloud Media Adapter.
+     * @throws {Error} If allowInstanceSharing is false and the container is already in use.
+     */
+    constructor();
+    /**
+     * @returns {SoundCloudWidget} The current SoundCloud widget instance.
+     * @throws {Error} If the widget has not been initialized.
+     */
+    get widget(): SoundCloudWidget;
+    /**
+     * @param {number} value - The volume level from 0.0 to 1.0.
+     * @throws {RangeError} If the volume is not between 0.0 and 1.0.
+     */
+    set volume(value: number);
+    /**
+     * @returns {number} The current volume level from 0.0 to 1.0.
+     */
+    get volume(): number;
+    /**
+     * Synchronously checks whether the SoundCloud media adapter is fully initialized and ready.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isReady(): boolean;
+    /**
+     * Asynchronously waits until the SoundCloud media adapter is fully initialized and ready.
+     * @returns {Promise<void>} A promise that resolves once the adapter is ready.
+     */
+    waitIsReady(): Promise<void>;
+    /**
+     * Retrieves a consolidated object containing all time-related metrics for the current media content.
+     * @returns {ContentTimeData} An object containing total, current, remaining time, and playback percentage.
+     */
+    getTimeData(): ContentTimeData;
+    /**
+     * Determines if the content is a valid SoundCloud URL or ID.
+     * @param {MediaContent} content - The media content to evaluate.
+     * @returns {boolean} True if the content is a SoundCloud link/ID, false otherwise.
+     */
+    static canHandle(content: MediaContent): boolean;
+    /**
+     * Determines if the content is a valid SoundCloud URL or ID.
+     * @param {MediaContent} content - The media content to evaluate.
+     * @returns {boolean} True if the content is a SoundCloud link/ID, false otherwise.
+     */
+    canHandle(content: MediaContent): boolean;
+    /**
+     * Plays the media content. If the player is already initialized with a different video,
+     * it will load the new video automatically.
+     *
+     * Example: https://api.soundcloud.com/tracks/XXXXXXXXX (From SoundCloud Embed)
+     * @param {MediaContent} content - The media content to play.
+     * @returns {Promise<void>}
+     * @throws {TypeError} If the content data is invalid.
+     * @throws {Error} If the track fails to load within the timeout period.
+     */
+    play(content: MediaContent): Promise<void>;
+    /**
+     * Pauses the current playback.
+     * @returns {Promise<void>}
+     */
+    pause(): Promise<void>;
+    /**
+     * Stops the playback completely.
+     * @returns {Promise<void>}
+     */
+    stop(): Promise<void>;
+    /**
+     * Seeks to a specific time in the media timeline.
+     * @param {number} timeMs - The target time in milliseconds.
+     * @returns {Promise<void>}
+     * @throws {TypeError} If timeMs is not a number.
+     */
+    seek(timeMs: number): Promise<void>;
+    /**
+     * Retrieves the current playback time.
+     * @returns {number} The current time in milliseconds.
+     */
+    getCurrentTime(): number;
+    /**
+     * Gets the total duration of the YouTube video.
+     * @returns {number} The total duration in milliseconds.
+     */
+    getTotalDuration(): number;
+    /**
+     * Gets the remaining time until the YouTube video ends.
+     * @returns {number} The remaining time in milliseconds.
+     */
+    getRemainingTime(): number;
+    /**
+     * Gets the percentage of the YouTube video that has been played.
+     * @returns {number} The percentage from 0 to 100.
+     */
+    getPlaybackPercentage(): number;
+    /**
+     * Sets the playback volume.
+     * @param {number} volume - The volume level from 0.0 to 1.0.
+     * @returns {void}
+     * @throws {RangeError} If volume is outside [0.0, 1.0].
+     */
+    setVolume(volume: number): void;
+    /**
+     * Gets the playback volume.
+     * @returns {number}
+     * @throws {RangeError} If volume is outside [0.0, 1.0].
+     */
+    getVolume(): number;
+    /**
+     * Retrieves the thumbnail URL for the currently loaded video with a specified quality.
+     * @returns {string|null} The thumbnail URL or null if no video is loaded.
+     */
+    getThumbnailUrl(): string | null;
+    /**
+     * Retrieves the metadata of the currently loaded SoundCloud music, returning a structured
+     * object containing details such as the audio ID, title, author, and duration.
+     * @returns {Promise<ContentData>}
+     */
+    getContentData(): Promise<ContentData>;
+    /**
+     * Cleans up the instance and disconnects from the shared player.
+     */
+    destroy(): void;
+}
+/**
+ * Asynchronously ensures the SoundCloud IFrame API is loaded and returns
+ * the SoundCloud Player constructor and the current player state mapping.
+ *
+ * @returns {Promise<{ Widget: typeof SoundCloudWidget }>}
+ * An object containing the Player constructor and the current player state mapping.
+ */
+declare const getSC: () => Promise<{
+    Widget: typeof SoundCloudWidget;
+}>;
+export { SoundCloudMediaAdapter, getEventValues, getSCWidget, loadSoundCloudApi, getSC };
+//# sourceMappingURL=SoundCloud.d.mts.map