diff --git a/MusicKit.d.ts b/MusicKit.d.ts index 8198e9e..cd64a11 100644 --- a/MusicKit.d.ts +++ b/MusicKit.d.ts @@ -42,9 +42,22 @@ export interface MusicKitConfiguration { } export interface MusicKitObject { + /** + * Configure MusicKit + * @param config - Configuration of MusicKit + */ 'configure': ( config: MusicKitConfiguration ) => Promise; + /** + * Retrieve the MusicKit instance after configuring it. + */ 'getInstance': () => MusicKitInstance; + /** + * Format an artwork object to get the formatted URL. + * @param artwork - The artwork object as retrieved from the API + * @param width - The desired width of the artwork + * @param height - The desired height of the artwork + */ 'formatArtworkURL': ( artwork: Artwork, width: number, height: number ) => string; } diff --git a/MusicKitAPI.d.ts b/MusicKitAPI.d.ts index 9866402..9c5baff 100644 --- a/MusicKitAPI.d.ts +++ b/MusicKitAPI.d.ts @@ -1,4 +1,12 @@ export interface MusicKitAPI { + /** + * This is the primary mean of accessing the Apple Music API. + * @see https://js-cdn.music.apple.com/musickit/v3/docs/index.html?path=/docs/reference-javascript-api--page + * @param path - The Apple Music API path to use + * @param params - The parameters to substitute in the path (params use Mustache syntax) + * @param options - Extra options to pass directly to the underlying fetch call. + * @returns The data in an object. The type varies across paths. + */ 'music': ( path: string, params: { diff --git a/MusicKitInstance.d.ts b/MusicKitInstance.d.ts index cf1c588..971f989 100644 --- a/MusicKitInstance.d.ts +++ b/MusicKitInstance.d.ts @@ -11,15 +11,39 @@ import type { export type MediaItem = object; export interface Queue { + /** + * The item at the `position` within `items` array + */ 'currentItem': MediaItem; + /** + * True if the `length` of the queue is `0` + */ 'isEmpty': boolean; + /** + * Array of `MediaItem`s in queue + */ 'items': MediaItem[]; + /** + * The number of `MediaItem`s in the queu + */ 'length': number; + /** + * The next item after the `currentItem` in the queue + */ 'nextPlayableItem': MediaItem; + /** + * The current index of the queue + */ 'position': number; + /** + * The previous item after the `currentItem` in the queue + */ 'previousPlayableItem': MediaItem; } +/** + * Used to set what is to be played + */ export interface QueueOptions { 'album'?: string; 'albums'?: string[]; @@ -29,6 +53,18 @@ export interface QueueOptions { 'playlists'?: string[]; 'song'?: string; 'songs'?: string[]; + /** + * Set the repeat mode when setting the queue + */ + 'repeatMode'?: PlayerRepeatMode; + /** + * Whether or not to start playing + */ + 'startPlaying'?: boolean; + /** + * The number of seconds to seek to in the current item + */ + 'startTime'?: number; } export interface SeekSeconds { @@ -37,52 +73,207 @@ export interface SeekSeconds { } export interface MusicKitInstance { + /** + * Access the Apple Music API + */ 'api': Readonly; + /** + * The current bitrate + */ 'bitrate': Readonly; + /** + * The duration of the `nowPlayingItem`, in seconds + */ 'currentPlaybackDuration': Readonly; + /** + * Percentage of playback completion of `nowPlayingItem`, between 0 and 1 + */ 'currentPlaybackProgress': Readonly; + /** + * The playhead position for the `nowPlayingItem`, in seconds + */ 'currentPlaybackTime': Readonly; + /** + * The remaining playback time for the `nowPlayingItem`, in seconds + */ 'currentPlaybackTimeRemaining': Readonly; + /** + * Set to true if user successfully signed in and authorized application via `authorize` + */ 'isAuthorized': Readonly; + /** + * True if audio is currently playing + */ 'isPlaying': Readonly; + /** + * The current MediaItem that is playing + */ 'nowPlayingItem': Readonly; + /** + * The index in the queue of the `nowPlayingItem` + */ 'nowPlayingItemIndex': Readonly; + /** + * The speed of playback, default is 1.0 + */ 'playbackRate': Readonly; + /** + * The state of playback, for more information. + */ 'playbackState': Readonly; + /** + * If a user is not subscribed to Apple Music + */ 'previewOnly': Readonly; + /** + * The current playback queue + */ 'queue': Readonly; + /** + * True if the playback queue is empty + */ 'queueIsEmpty': Readonly; - 'repeatMode': Readonly; - 'seekSeconds': Readonly; - 'shuffleMode': Readonly; + /** + * Repeat mode for the player. Set here to control mode + */ + 'repeatMode': PlayerRepeatMode; + /** + * Used to configure seek behaviour, in seconds + */ + 'seekSeconds': SeekSeconds | undefined; + /** + * Control the shuffle mode for the player + */ + 'shuffleMode': PlayerShuffleMode; + /** + * The id of the authorized user's storefront + */ 'storefrontCountryCode': Readonly; + /** + * The storefrontId as configured for this `MusicKitInstance` + */ 'storefrontId': Readonly; - 'videoContainerElement': Readonly; - 'volume': Readonly; + /** + * Set this to allow for playing music videos in the specified element. + */ + 'videoContainerElement': HTMLVideoElement | undefined; + /** + * The volume of the `HTMLMediaElement`, between 0 and 1 + */ + 'volume': number; + /** + * Listen to an event on the `MusicKitInstance` + * @param name - The Event name, see https://js-cdn.music.apple.com/musickit/v3/docs/index.html?path=/story/reference-javascript-events--page + * @param callback - a callable function, whose arguments depend on the event listened to + * @param options - Any further options (currently only 'once', which, if set to true, removes the listener after it was triggered once) + */ 'addEventListener': ( name: string, callback: CallableFunction, options: { 'once': boolean } ) => void; + /** + * Authorize a user + * @returns Promise resolving to string representing user, or if authorization failed, undefined + */ 'authorize': () => Promise; + /** + * Play `MediaItem` at specified index in Queue + * @param index - The index to play at + */ 'changeToMediaAtIndex': ( index: number ) => Promise; + /** + * Change to a `MediaItem` or `string` representation of one instead of index + * @param descriptor - The item + */ 'changeToMediaItem': ( descriptor: MediaItem | string ) => Promise; + /** + * Change the user's storefront to `storefrontId`` + * @param storefrontId - The storefront to change to + */ 'changeUserStorefront': ( storefrontId: string ) => Promise; + /** + * Clears the queue + */ 'clearQueue': () => Promise; + /** + * Close full-screen element, when applicable + */ 'exitFullscreen': () => void; + /** + * Sets `volume` to `0`, previous value is stored + */ 'mute': () => void; + /** + * Pause playback + */ 'pause': () => void; + /** + * Starts playback of `nowPlayingItem` + */ 'play': () => void; + /** + * Inserts the `MediaItem`(s) defined by `QueueOptions` at the position indicated in the current queue. + * @param position - The index at which to insert + * @param options - What to add to the queue + */ 'playAt': ( position: number, options: QueueOptions ) => Promise; + /** + * Inserts the item(s) after the last item in the current queue + * @param options - What to add to the queue + */ 'playLater': ( options: QueueOptions ) => Promise; - 'playNext': ( options: QueueOptions, clear: boolean ) => Promise; + /** + * Inserts the item(s) after the `nowPlayingItem` + * @param options - What to add to the queue + * @param clear - Whether or not to clear the queue again + */ + 'playNext': ( options: QueueOptions, clear?: boolean ) => Promise; + /** + * Remove the event listener again + * @param name - The name of the event to remove for + * @param callback - The used callback function on addEventListener + */ 'removeEventListener': ( name: string, callback: CallableFunction ) => void; - 'requestFullscreen': () => void; + /** + * Make element full-screen + * @param element - The element to make full-screen + */ + 'requestFullscreen': ( element: HTMLElement ) => void; + /** + * Seeks back `seekSeconds.BACK` seconds + */ 'seekBackward': () => Promise; + /** + * Seeks forward `seekSeconds.BACK` seconds + */ 'seekForward': () => Promise; + /** + * Seek to a specific time in the song + * @param time - the time in seconds to move to + */ 'seekToTime': ( time: number ) => Promise; + /** + * Set items for the playback queue + * @param options - Description of what is to be added to the queue + */ 'setQueue': ( options: QueueOptions ) => Promise; + /** + * Skip to next song in queue + */ 'skipToNextItem': () => Promise; + /** + * Skip to previous song in queue + */ 'skipToPreviousItem': () => Promise; + /** + * Stops the `nowPlayingItem` + */ 'stop': () => void; + /** + * Unauthorizes the user from the application + */ 'unauthorize': () => Promise; + /** + * Unmute playback volume, setting it to value before muting + */ 'unmute': () => void; }