cody-music/dist/lib/apis.d.ts

mac osx spotify and itunes music player controller, spotify audio features, itunes and spotify genre, and playlist control

import { PlayerName, Track, PlayerDevice, SpotifyAudioFeature, PlaylistItem, CodyResponse, PlayerContext, SpotifyAuthState } from "./models";
import { SpotifyUser } from "./profile";
/**
 * Initialize/set music credentials and settings
 * @param config <CodyConfig>
 */
export declare function setConfig(config: any): void;
/**
 * Valid types are: album, artist, playlist, and track
 * keywords: send the keywords to search against.
 * Use specific filter name if you want to search against certain
 * fields.
 * Example searchTracks("track:what a time artist:tom")
 *
 * @param string
 * @param limit (min of 1 and a max of 50)
 */
export declare function searchTracks(keywords: string, limit?: number): Promise<any>;
/**
 * Valid types are: album, artist, playlist, and track
 * keywords: send the keywords to search against.
 * Use specific filter name if you want to search against certain
 * fields.
 * Example searchTracks("track:what a time artist:tom")
 *
 * @param string
 * @param limit (min of 1 and a max of 50)
 */
export declare function searchArtists(keywords: string, limit?: number): Promise<any>;
/**
 * Returns true if the user has granted Mac OS access for iTunes control
 */
export declare function isItunesAccessGranted(): boolean;
/**
 * Returns false if cody music has been configured to to disable it
 * or if it's the OS is not Mac,
 * otherwise it's set to true by default
 */
export declare function isItunesDesktopEnabled(): any;
/**
 * Returns false if cody music has been configured to to disable it
 * or if it's the OS is not Mac,
 * otherwise it's set to true by default
 */
export declare function isItunesDesktopSongTrackingEnabled(): any;
/**
 * Get the Spotify accessToken provided via through the setConfig api
 * @returns {string} the spotify access token string
 */
export declare function getSpotifyAccessToken(): any;
/**
 * Refresh the Spotify accessToken
 * @returns {Promise<boolean>} whether or not the refresh was successful
 */
export declare function refreshSpotifyAccessToken(): Promise<boolean>;
/**
 * Returns false if cody music has been configured to to disable it,
 * otherwise it's set to true by default
 */
export declare function isSpotifyDesktopEnabled(): any;
/**
 * Checks if the Spotify desktop or web player is running or not
 * @returns {Promise<boolean>}
 */
export declare function isSpotifyRunning(): Promise<any>;
/**
 * Checks if the iTunes desktop player is running or not
 * @returns {Promise<boolean>}
 */
export declare function isItunesRunning(): Promise<any>;
/**
 * Checks if one of the specified players is running
 * @param player {spotify|spotify-web|itunes}
 * @returns {Promise<boolean>}
 */
export declare function isPlayerRunning(player: PlayerName): Promise<any>;
/**
 * Returns whether there's an active track,
 * (spotify web, spotify desktop, or itunes desktop)
 * @returns {Promise<boolean>}
 */
export declare function hasActiveTrack(): Promise<boolean>;
/**
 * Returns the recommended tracks.
 * @param trackIds (optional) track IDs or URIs (5 max)
 * @param limit (optional) will default to 40 if not specified
 * @param market (optional) will default to none if not specified
 * @param min_popularity (optional) will default to a min or 20
 * @param target_popularity (optional) will default to 90
 * @param seed_genres (optional) the supported spotify genres (5 max)
 * @param seed_genres (optional) artist IDs or URIs (5 max)
 * @param features (optional) supports the tunable track attributes using min_*, max_*, and target_*
 *   i.e. {max_valence: 0.3, target_valence: 0.1}
 */
export declare function getRecommendationsForTracks(trackIds?: string[], limit?: number, market?: string, min_popularity?: number, target_popularity?: number, seed_genres?: string[], seed_artists?: string[], features?: any): Promise<Track[]>;
/**
 * Returns the currently running track.
 * Spotify web, desktop, or itunes desktop.
 * If it finds a spotify device but it's not playing, and mac iTunes is not playing
 * or paused, then it will return the Spotify track.
 * It will return an empty Track object if it's unable to
 * find a running track.
 * @returns {Promise<Track>}
 **/
export declare function getRunningTrack(): Promise<Track>;
/**
 * Fetch the recently played spotify tracks
 * @param limit - The maximum number of items to return. Default: 50. Minimum: 1. Maximum: 50
 */
export declare function getSpotifyRecentlyPlayedTracks(limit?: number): Promise<Track[]>;
/**
 * Fetch the recently played spotify tracks
 * @param limit - The maximum number of items to return. Default: 50. Minimum: 1. Maximum: 50
 * @param before - Returns all items before (but not including) this cursor position
 */
export declare function getSpotifyRecentlyPlayedBefore(limit?: number, before?: number): Promise<CodyResponse>;
/**
 * Fetch the recently played spotify tracks
 * @param limit - The maximum number of items to return. Default: 50. Minimum: 1. Maximum: 50
 * @param after - Returns all items before (but not including) this cursor position
 */
export declare function getSpotifyRecentlyPlayedAfter(limit?: number, after?: number): Promise<CodyResponse>;
/**
 * Fetch the spotify player context
 * Info about the device, is playing state, etc.
 */
export declare function getSpotifyPlayerContext(): Promise<PlayerContext>;
/**
 * Returns a track by the given spotify track id
 * @param id
 * @param includeFullArtistData (optional - if true it will return full artist info)
 * @package includeAudioFeaturesData (optional)
 * @param includeGenre (optional)
 */
export declare function getSpotifyTrackById(id: string, includeFullArtistData?: boolean, includeAudioFeaturesData?: boolean, includeGenre?: boolean): Promise<Track>;
/**
 * Returns tracks by the given spotify track ids
 * @param ids
 * @param includeFullArtistData (optional - if true it will return full artist info)
 * @package includeAudioFeaturesData (optional)
 * @param includeGenre (optional)
 */
export declare function getSpotifyTracks(ids: string[], includeFullArtistData?: boolean, includeAudioFeaturesData?: boolean, includeGenre?: boolean): Promise<Track[]>;
/**
 * Returns the track of a given player {spotify|spotify-web|itunes}
 * - Spotify does not return a "genre"
 * - duration is in milliseconds
 * @param player {spotify|spotif-web|itunes}
 * @returns {artist, album, genre, disc_number, duration, played_count, track_number, id, name, state}
 */
export declare function getTrack(player: PlayerName): Promise<Track>;
/**
 * Returns the tracks that are found for itunes
 * @param player {itunes}
 * @param playListName
 */
export declare function getTracksByPlaylistName(player: PlayerName, playListName: string): Promise<Track[]>;
export declare function getSpotifyAlbumTracks(albumId: string): Promise<Track[]>;
/**
 * Currently only returns Spotify Web tracks not associated with a playlist.
 * @param player
 * @param qsOptions
 */
export declare function getSpotifyLikedSongs(qsOptions?: any): Promise<Track[]>;
/**
 * Currently only returns Spotify Web tracks not associated with a playlist.
 * @param player
 * @param qsOptions
 */
export declare function getSavedTracks(player: PlayerName, qsOptions?: any): Promise<Track[]>;
/**
 * Returns a playlist by ID
 * @param playlist_id ID is preferred, but we'll transform a URI to an ID
 */
export declare function getSpotifyPlaylist(playlist_id: string): Promise<PlaylistItem>;
/**
 * Returns the tracks that are found by the given playlist name
 * - currently spofity-web support only
 * @param player {spotify-web}
 * @param playlist_id (optional)
 * @param qsOptions (optional) {offset, limit}
 */
export declare function getPlaylistTracks(player: PlayerName, playlist_id: string, qsOptions?: any): Promise<CodyResponse>;
/**
 * Plays a playlist at the beginning if the starting track id is not provided.
 * @param playlistId either the ID or URI of the playlist
 * @param startingTrackId either the ID or URI of the track
 * @param deviceId
 */
export declare function playSpotifyPlaylist(playlistId: string, startingTrackId?: string, deviceId?: string): Promise<CodyResponse>;
/**
 * Plays a specific track on the Spotify or iTunes desktop
 * @param player
 * @param params
 * spotify example  ["spotify:track:0R8P9KfGJCDULmlEoBagcO", "spotify:album:6ZG5lRT77aJ3btmArcykra"]
 *   -- provide the trackID then the album or playlist ID
 *   -- they can either be in either URI or ID format
 * itunes example   ["Let Me Down Slowly", "MostRecents"]
 *   -- provide the track name then the playlist name
 */
export declare function playTrackInContext(player: PlayerName, params: any[]): Promise<any>;
/**
 * Mac iTunes only
 * This will allow you to play a playlist starting at a specific playlist track number.
 */
export declare function playItunesTrackNumberInPlaylist(playlistName: string, trackNumber: number): Promise<any>;
/**
 * Quits/closes the mac Spotify or iTunes player
 * @param player
 */
export declare function quitMacPlayer(player: PlayerName): Promise<any>;
/**
 * This is only meant for Mac iTunes or Mac Spotify desktop
 * @param player
 * @param params
 */
export declare function playTrackInLibrary(player: PlayerName, params: any[]): Promise<any>;
/**
 * Initiate and play the specified Spotify device
 * @param device_id {string}
 */
export declare function playSpotifyDevice(device_id: string): Promise<CodyResponse>;
/**
 * Initiate and play the specified Spotify device
 * @param device_id {string}
 * @param play {boolean} true to play and false to keep current play state
 */
export declare function transferSpotifyDevice(device_id: string, play: boolean): Promise<CodyResponse>;
/**
 * Check if the access/refresh tokens have expired
 */
export declare function accessExpired(): Promise<boolean>;
/**
 * Fetch the user's profile
 */
export declare function getUserProfile(): Promise<SpotifyUser>;
/**
 * Helper API to return whether or not the user is logged in to their spotify account or not.
 * It's not fool proof as it only determines if there are any devices found or not.
 * {oauthActivated, loggedIn}
 */
export declare function spotifyAuthState(): Promise<SpotifyAuthState>;
/**
 * Initiate the play command for a specific player
 * @param player {spotify|spotify-web|itunes}
 * @param options { uris, device_id }
 * example
 * -- the uris can be in either URI or ID format
 * {device_id: <spotify_device_id>, uris: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:1301WleyT98MSxVHPZCA6M"], context_uri: <playlist_uri, album_uri>}
 */
export declare function play(player: PlayerName, options?: any): Promise<any>;
/**
 * Play a specific spotify track by trackId (it can be the URI or the ID)
 * @param trackId
 * @param deviceId (optional)
 */
export declare function playSpotifyTrack(trackId: string, deviceId?: string): Promise<CodyResponse>;
/**
 * Initiate the play command for a given trackId for a specific player
 * @param player {spotify|spotify-web|itunes}
 * @param trackId {any (string|number)}
 */
export declare function playTrack(PlayerName: PlayerName, trackId: any): Promise<any>;
/**
 * Initiate the pause command for a given player
 * @param player {spotify|spotify-web|itunes}
 * @param options
 */
export declare function pause(player: PlayerName, options?: any): Promise<any>;
/**
 * Initiate the play/pause command for a given player
 * @param player {spotify|spotify-web|itunes}
 * @param options
 */
export declare function playPause(player: PlayerName): Promise<any>;
/**
 * Initiate the next command for a given player
 * @param player {spotify|spotify-web|itunes}
 * @param options
 */
export declare function next(player: PlayerName, options?: any): Promise<any>;
/**
 * Initiate the previous command for a given player
 * @param player {spotify|spotify-web|itunes}
 * @param options
 */
export declare function previous(player: PlayerName, options?: any): Promise<any>;
/**
 * Repeats a playlist
 * @param player
 * @param deviceId
 */
export declare function setRepeatPlaylist(player: PlayerName, deviceId?: string): Promise<any>;
/**
 * Repeats a track
 * @param player
 * @param deviceId
 */
export declare function setRepeatTrack(player: PlayerName, deviceId?: string): Promise<any>;
/**
 * Turn repeat off
 * @param player
 * @param deviceId
 */
export declare function setRepeatOff(player: PlayerName, deviceId?: string): Promise<any>;
/**
 * Turn on/off repeat for a given player
 * @param player {spotify|spotify-web|itunes}
 * @param options
 */
export declare function setRepeat(player: PlayerName, repeat: boolean, deviceId?: string): Promise<any>;
/**
 * Turn on/off shuffling for a given player
 * @param player {spotify|spotify-web|itunes}
 */
export declare function setShuffle(player: PlayerName, shuffle: boolean, deviceId?: string): Promise<any>;
/**
 * Return whether shuffling is on or not
 * @param player {spotify|spotify-web|itunes}
 */
export declare function isShuffling(player: PlayerName): Promise<any>;
/**
 * Returns whether the player is on repeat or not
 * - spotify returns true or false, and itunes returns "off", "one", "all"
 * @param player {spotify|spotify-web|itunes}
 */
export declare function isRepeating(player: PlayerName): Promise<any>;
/**
 * Update the players volume
 * @param player {spotify|spotify-web|itunes}
 * @param volume {0-100}
 */
export declare function setVolume(player: PlayerName, volume: number): Promise<any>;
/**
 * Increments the players volume by a number
 * @param player {spotify|spotify-web|itunes}
 */
export declare function volumeUp(player: PlayerName): Promise<any>;
/**
 * Decrements the players volume by a number
 * @param player {spotify|spotify-web|itunes}
 */
export declare function volumeDown(player: PlayerName): Promise<any>;
/**
 * Mutes the players volume
 * @param player {spotify|spotify-web|itunes}
 */
export declare function mute(player: PlayerName, device_id?: string): Promise<any>;
/**
 * Unmutes the players volume
 * @param player {spotify|spotify-web|itunes}
 */
export declare function unmute(player: PlayerName, device_id?: string): Promise<any>;
/**
 * Unmutes the players volume
 * @param player {spotify|spotify-web|itunes}
 */
export declare function setItunesLoved(loved: boolean): Promise<any>;
/**
 * Save tracks to your liked playlist
 * @param trackIds (i.e. ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"])
 */
export declare function saveToSpotifyLiked(trackIds: string[]): Promise<CodyResponse>;
/**
 * Remove tracks from your liked playlist
 * @param trackIds (i.e. ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"])
 */
export declare function removeFromSpotifyLiked(trackIds: string[]): Promise<CodyResponse>;
/**
 * Returns the playlists for a given player
 * @param player {spotify|spotify-web|itunes}
 * @param (optional) {limit, offset, all}
 */
export declare function getPlaylists(player: PlayerName, qsOptions?: any): Promise<PlaylistItem[]>;
/**
 * Get the full list of the playlist names for a given player
 * @param player {spotify|spotify-web|itunes}
 * @param qsOptions (optional) {limit, offset}
 */
export declare function getPlaylistNames(player: PlayerName, qsOptions?: any): Promise<string[]>;
/**
 * Launches a player device
 * @param playerName {spotify|spotify-web|itunes}
 * @param options (spotify-web only) {playlist_id | album_id | track_id }
 */
export declare function launchPlayer(playerName: PlayerName, options?: any): Promise<any>;
/**
 * Plays a Spotify track within a playlist.
 * It will also launch Spotify if it is not already available by checking the device Ids.
 * @param trackId (optional) If it's not supplied then the playlistId must be provided
 * @param playlistId (optional) If it's not supplied then the trackId must be provided
 * @param playerName (optional) SpotifyWeb or SpotifyDesktop
 */
export declare function launchAndPlaySpotifyTrack(trackId?: string, playlistId?: string, playerName?: PlayerName): Promise<void>;
/**
 * Plays a Spotify Mac Desktop track within a playlist.
 * It will also launch Spotify if it is not already available by checking the device Ids.
 * @param trackId (optional) If it's not supplied then the playlistId must be provided
 * @param playlistId (optional) If it's not supplied then the trackId must be provided
 */
export declare function playSpotifyMacDesktopTrack(trackId?: string, playlistId?: string): void;
/**
 * Returns available Spotify devices
 * @returns {Promise<PlayerDevice[]>}
 */
export declare function getSpotifyDevices(): Promise<PlayerDevice[]>;
/**
 * Returns the genre for a provided arguments
 * @param artist {string} is required
 * @param songName {string} is optional
 * @param spotifyArtistId {string} is optional
 */
export declare function getGenre(artist: string, songName?: string, spotifyArtistId?: string): Promise<string>;
/**
 * Returns the spotify genre for a provided arguments
 * @param artist {string} is required
 * @param spotifyArtistId {string} is optional
 */
export declare function getSpotifyGenre(artist: string): Promise<string>;
/**
 * Returns the spotify genre for a provided arguments
 * @param spotifyArtistId {string} is required
 */
export declare function getSpotifyGenreByArtistId(spotifyArtistId: string): Promise<string>;
/**
 * Returns the highest frequency single genre from the provided list
 * @param genreList
 */
export declare function getHighestFrequencySpotifyGenre(genreList: string[]): string;
/**
 * Returns the recent top tracks Spotify for a user.
 */
export declare function getTopSpotifyTracks(): Promise<Track[]>;
/**
 * Returns the audio features of the given track IDs
 * @param ids these are the track ids (sans spotify:track)
 */
export declare function getSpotifyAudioFeatures(ids: string[]): Promise<SpotifyAudioFeature[]>;
/**
 * Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)
 * @param name the name of the playlist you want to create
 * @param isPublic if the playlist will be public or private
 * @param description (Optioal) displayed in Spotify Clients and in the Web API
 */
export declare function createPlaylist(name: string, isPublic: boolean, description?: string): Promise<CodyResponse>;
/**
 * Deletes a playlist of a given playlist ID.
 * @param playlist_id (uri or id)
 */
export declare function deletePlaylist(playlist_id: string): Promise<CodyResponse>;
/**
 * Follow a playlist of a given playlist ID.
 * @param playlist_id (uri or id)
 */
export declare function followPlaylist(playlist_id: string): Promise<CodyResponse>;
/**
 * Replace tracks of a given playlist. This will wipe out
 * the current set of tracks and add the tracks specified.
 * @param playlist_id
 * @param track_ids
 */
export declare function replacePlaylistTracks(playlist_id: string, track_ids: string[]): Promise<CodyResponse>;
/**
 * Add tracks to a given Spotify playlist.
 * @param playlist_id the Spotify ID for the playlist
 * @param tracks Tracks should be the uri (i.e. "spotify:track:4iV5W9uYEdYUVa79Axb7Rh")
 * but if it's only the id (i.e. "4iV5W9uYEdYUVa79Axb7Rh") this will add
 * the uri part "spotify:track:"
 * @param position The position to insert the tracks, a zero-based index.
 */
export declare function addTracksToPlaylist(playlist_id: string, tracks: string[], position?: number): Promise<CodyResponse>;
/**
 * Remove tracks from a given Spotify playlist.
 * @param playlist_id the Spotify ID for the playlist
 * @param tracks Tracks should be the uri (i.e. "spotify:track:4iV5W9uYEdYUVa79Axb7Rh")
 * but if it's only the id (i.e. "4iV5W9uYEdYUVa79Axb7Rh") this will add
 * the uri part "spotify:track:"
 */
export declare function removeTracksFromPlaylist(playlist_id: string, tracks: string[]): Promise<CodyResponse>;
/**
 * Returns whether or not the spotify access token has been provided.
 * @returns <boolean>
 */
export declare function requiresSpotifyAccessInfo(): boolean;
/**
 * Deprecated - use "getTrack(player)"
 */
export declare function getPlayerState(player: PlayerName): Promise<Track>;
/**
 * Deprecated - use "getRunningTrack()" instead
 */
export declare function getCurrentlyRunningTrackState(): Promise<Track>;
/**
 * Deprecated - please use "getPlayerState"
 */
export declare function getState(player: PlayerName): Promise<Track>;
/**
 * Deprecated - please use "launchPlayer('spotify')"
 **/
export declare function startSpotifyIfNotRunning(): Promise<any>;
/**
 * Deprecated - please use "launchPlayer('itunes')"
 */
export declare function startItunesIfNotRunning(): Promise<any>;
/**
 * Deprecated - please use "isSpotifyRunning" or "isItunesRunning"
 */
export declare function isRunning(player: PlayerName): Promise<boolean>;
/**
 * Deprecated - please use "setRepat(player, repeat)"
 */
export declare function repeatOn(player: PlayerName): Promise<any>;
/**
 * Deprecated - please use "setRepat(player, repeat)"
 */
export declare function repeatOff(player: PlayerName): Promise<any>;
/**
 * Deprecated - please use "unmute(player)"
 */
export declare function unMute(player: PlayerName): Promise<any>;
/**
 * Deprecated - please use "setConfig(config: CodyConfig)"
 * Set Credentials (currently only supports Spotify)
 * Accepted credentials: clientId, clientSecret, refreshToken, accessToken
 * @param credentials
 */
export declare function setCredentials(credentials: any): void;
/**
 * Deprecated - please use "getSpotifyAccessToken()"
 * Get the accessToken provided via through the setCredentials api
 * @returns {string} the access token string
 */
export declare function getAccessToken(): any;