Reference

import export shorthand

Get an existing, readable ini file name, create it if necessary

apply_and_wait_for_implicit_grant(;scopes::Vector{String} = DEFAULT_IMPLICIT_GRANT)

1. Start the negotiations for an extended scope!
2. Wait for it!

The result shows up in console, and in the stored credentials.

authorize()
-> Bool

Get and store client credentials. Any other credentials will be dropped.

body_string

Encodes the arguments as expected in a HTTP message body.

Type info and strurcture is in JSON format.

We define our own types through StructTypes and JSON3 in 'types.jl'.

Empty values => the key is also considered redundant.

build_query_string(xs::Vararg{String,N} where N)

Includes separators if needed, for urlstrings.

coloredfunctioncallstring(loaded, funcsymb, namesby_func) - String

coloredfunctioncall_string(funcsymb, argvals) -> String

" colored_repr(x) -> String

String which can be 'pretty-printed': colourful indication of types which after displaying can still be copied for parsing as strings.

Called by select_functions

get_authorization_field(;scope = "client-credentials", additional_scope = "")

For Spotify requests, provide authorization field. If 'scope' is outside current grant, apply to user / Spotify for more.

Get id and secret as 32-byte string, no encryption

hasigaccess_token()

isfunctionloaded(foo::Symbol)

julia> using Spotify.Library
julia> Spotify.is_function_loaded(:library_get_saved_shows)
true

julia> Spotify.is_function_loaded(:markets_get)
false

ismoduleloaded(foo::Symbol)

julia> using Spotify.Library
julia> Spotify.is_module_loaded(:Library)
true

julia> Spotify.is_module_loaded(:Artists)
false

launch_a_browser_that_asks_for_implicit_grant(;scopes::Vector{String} = DEFAULT_IMPLICIT_GRANT)

Called by apply_and_wait_for_implicit_grant.

Launch an available browser with an uri that contains the scope we are looking for. Exit at once.

launch_async_single_grant_receiving_server()

Called by apply_and_wait_for_implicit_grant.

The server runs asyncronously. It stays open a certain time, waiting for a request containing a new grant. The grant is negotiated between Spotify and the user of the browser we launch.

The request is received from the browser, which got it from Spotify. This server hands the request over to receive_grant_as_request.

Server closes after some time, or when the grant has been received and stored.

Constructs windows launch command

Called by select_calls after user interaction

menuitems(funcsymbs, funcloaded, namesby_func) -> Vector{String}

Called by select_functions

Sub-modules of Spotify, included ones that are not loaded. Exclude JSON3.

parse_copied_link(s)
-> SpPlaylistId, SpTrackId, SpArtistId, SpId, SpAlbumId, SpCategoryId, SpEpisodeId, SpShowId

Parse links copied from Spotify to a type which can be used in API wrapper calls:

Spotify app -> Right click -> Share -> Copy link to clipboard

Spotify app -> Right click -> Share -> Copy embed code to clipboard

julia> track_id = parse_copied_link("https://open.spotify.com/track/0pXkRXjPFg0NCLgPTyJKwc?si=6e74b17f726244d7")
spotify:track:0pXkRXjPFg0NCLgPTyJKwc

julia> artist_id = parse_copied_link("<iframe style="border-radius:12px" src="https://open.spotify.com/embed/artist/7FpOGzPK8QgIpFOky6PnGk?utm_source=generator" width="100%" height="352" frameBorder="0" allowfullscreen="" allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture" loading="lazy"></iframe>"

player_get_current_track(;additional_types = "track", market = "")

Summary: Get the object currently being played on the user's Spotify account.

Optional keywords

• additional_types : "track" (default) or "episode"
• market : An ISO 3166-1 alpha-2 country code. If a country code is specified, only episodes that are available in that market will be returned. Default is set to "US".

Example

julia> player_get_current_track()[1]
JSON3.Object{Base.CodeUnits{UInt8, String}, Vector{UInt64}} with 7 entries:
  :timestamp              => 1636491068506
  :context                => {…
  :progress_ms            => 5265
  :item                   => {…
  :currently_playing_type => "track"
  :actions                => {…
  :is_playing             => true

Reference

player_get_devices()

Summary: Get information about a user’s available devices.

Example

julia> player_get_devices()[1]
JSON3.Object{Base.CodeUnits{UInt8, String}, Vector{UInt64}} with 1 entry:
  :devices => JSON3.Object[{…

Reference

player_get_state(;additional_types = "track", market = "")

Summary: Get information about the user’s current playback state, including track or episode, progress, and active device.

Optional keywords

• additional_types : "track" (default) or "episode"
• market : An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter. Note: If neither market or user country are provided, the content is considered unavailable for the client. Users can view the country that is associated with their account in the account settings. NOTE: Default is set to "".

Example

julia> player_get_state()[1]
JSON3.Object{Base.CodeUnits{UInt8, String}, Vector{UInt64}} with 10 entries:
  :device                 => {…
  :shuffle_state          => false
  :repeat_state           => "off"
  :timestamp              => 1636493367689
  :context                => {…
  :progress_ms            => 66454
  :item                   => {…
  :currently_playing_type => "track"
  :actions                => {…
  :is_playing             => true

Reference

player_pause(;device_id = "")

Summary: Pause playback on the user's account.

Optional keywords

• device_id The id of the device this command is targeting. If not supplied, the user's currently active device is the target. Example value: "0d1841b0976bae2a3a310dd74c0f3df354899bc8"

Example

julia> device_id = player_get_devices()[1].devices[1].id;

julia> player_pause(;device_id)
({}, 0)

julia> player_pause() # Fails because we already paused, see `player_resume_playback`
┌ Info: 403 (code meaning): Forbidden - The server understood the request, but is refusing to fulfill it.
└               (response message): Player command failed: Restriction violated

Reference

player_resume_playback(;device_id = "", context_uri = "", uris = "", offset = 0, position_ms = 0)

Summary: Start a new context or resume current playback on the user's active device.

Optional keywords

• device_id The id of the device this command is targeting. If not supplied, the user's currently active device is the target. Example value:

"0d1841b0976bae2a3a310dd74c0f3df354899bc8"

• context_uri Spotify URI of the context to play. Valid contexts are albums, artists & playlists. {context_uri:"spotify:album:1Je1IMUlBXcx1Fz0WE7oPT"}
• uris Vector of arguments to (queue and) play. Accepts string types (with prefixes like 'spotify:track:') or types like SpTrackId, SpEpisodeId.
• offset Indicates from where in the context playback should start. Only available when context_uri corresponds to an album or playlist object "position" is zero based and can’t be negative. Example: "offset": {"position": 5} "uri" is a string representing the uri of the item to start at. Example: "offset": {"uri": "spotify:track:1301WleyT98MSxVHPZCA6M"}
• position_ms Integer

Examples

julia> context_uri = SpAlbumId("1XORY4rQNhqkZxTze6Px90")
spotify:album:1XORY4rQNhqkZxTze6Px90

julia> offset = Dict("position" => 35) # Song no.
Dict{String, Int64} with 1 entry:
  "position" => 35
julia> position_ms = 59000
59000
julia> player_resume_playback(;context_uri, offset, position_ms)[1]
{}

We can alternatively specify a sequence of tracks, here no. 1 and 35 from the same album. We can set the starting position for the first of those:

julia> uris = SpTrackId.(["4SFBV7SRNG2e2kyL1F6kjU", "46J1vycWdEZPkSbWUdwMZQ"])
2-element Vector{SpTrackId}:
 spotify:track:4SFBV7SRNG2e2kyL1F6kjU
 spotify:track:46J1vycWdEZPkSbWUdwMZQ

julia> player_resume_playback(;uris, position_ms = 82000)[1]
{}

Reference

player_seek(position_ms; device_id = "")

Summary: Seeks to the given position in the user’s currently playing track.

Arguments

• position_ms The position in milliseconds to seek to. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

Optional keywords

• device_id The id of the device this command is targeting. If not supplied, the user's currently active device is the target. Example value:

Reference

player_skip_to_next(;device_id = "")

Summary: Skips to next track in the user’s queue.

• device_id The id of the device this command is targeting. If not supplied, the user's currently active device is the target.

Reference

player_skip_to_previous(;device_id = "")

Summary: Skips to previous track in the user’s queue.

• device_id The id of the device this command is targeting. If not supplied, the user's currently active device is the target.

Reference

receive_grant_as_request(req::HTTP.Request)

This handler is called by launch_async_single_grant_receiving_server, when the server receives a request from the browser. We return a response for user feedback, but the main effect is that we update the credentials stored in memory.

request_to_stdout(method, url, body, authorizationfield, logstate, no_mistake)

Print a request after it is made.

select_calls()

Open an interactive menu in the console. User picks modules, then functions in those. Calls are made with default arguments, defined in src/lookup/paramname_default_dic.

Console output is formatted for pasting into inline documentation.

select_functions()

Pick a subset of loaded functions for calling in sequence with default arguments.

Access current stored credentials

spotify_request(url_ext::String, method::String= "GET"; 
                scope = "client-credentials", additional_scope = "", 
                body = "", logstate = LOGSTATE)
 -> (r::JSON3.Object, retry_in_seconds::Int)

Access the Spotify Web API. This is called by every function in /by_console_doc/ and /by_reference_doc/. Error results return an empty Object. Errors are written to 'stderr', expect for 'API rate limit exceeded', as the output would typically occur in the middle of recursive calls.

urlstring

Encodes the arguments as expected in a query string.

Type info is seldom necessary, because the type of arguments is given by the API endpoint.

Empty argument values => the argument name is considered redundant.

waitforigaccess(; timeoutin_seconds = 30)

All web API arguments are simple strings. Spotify.jl defines some types that have context-aware representations. Type names are Sp____Id.

Examples

Make an instance

julia> track_id = SpTrackId()        # output is colored
spotify:track:0WdUHon5tYn2aKve13psfy

In simple web API function calls like "audio-analysis" below, the type of the argument is obvious from the context; "spotify:track" is superfluous.

julia>"audio-analysis/$track_id"
"audio-analysis/0WdUHon5tYn2aKve13psfy"

The actual Julia wrapper function is duck typed, meaning that the 'track_id' argument type can be both String or SpTrackId. Numbers on the other hand, would produce an error.

function tracks_get_audio_analysis(track_id)
    tid = SpTrackId(track_id)
    spotify_request("audio-analysis/$tid")
end

Other API calls need more type information. Spotify understands the 'Spotify URI' ) format, where type is denoted by string prefixes. Such functions use a 'request body' to pass arguments. Request bodies often contain several arguments in a structure, for example a list or a dictionary. Request bodies comply with the JSON format.

So in a 'request body', we would represent 'track_id' like this:

julia> Spotify.JSON3.write(track_id)
"\"spotify:track:0WdUHon5tYn2aKve13psfy\""

All web API arguments are simple strings. Spotify.jl defines some types that have context-aware representations. Type names are Sp____Id.

Examples

Make an instance

julia> track_id = SpTrackId()        # output is colored
spotify:track:0WdUHon5tYn2aKve13psfy

In simple web API function calls like "audio-analysis" below, the type of the argument is obvious from the context; "spotify:track" is superfluous.

julia>"audio-analysis/$track_id"
"audio-analysis/0WdUHon5tYn2aKve13psfy"

The actual Julia wrapper function is duck typed, meaning that the 'track_id' argument type can be both String or SpTrackId. Numbers on the other hand, would produce an error.

function tracks_get_audio_analysis(track_id)
    tid = SpTrackId(track_id)
    spotify_request("audio-analysis/$tid")
end

Other API calls need more type information. Spotify understands the 'Spotify URI' ) format, where type is denoted by string prefixes. Such functions use a 'request body' to pass arguments. Request bodies often contain several arguments in a structure, for example a list or a dictionary. Request bodies comply with the JSON format.

So in a 'request body', we would represent 'track_id' like this:

julia> Spotify.JSON3.write(track_id)
"\"spotify:track:0WdUHon5tYn2aKve13psfy\""

All web API arguments are simple strings. Spotify.jl defines some types that have context-aware representations. Type names are Sp____Id.

Examples

Make an instance

julia> track_id = SpTrackId()        # output is colored
spotify:track:0WdUHon5tYn2aKve13psfy

In simple web API function calls like "audio-analysis" below, the type of the argument is obvious from the context; "spotify:track" is superfluous.

julia>"audio-analysis/$track_id"
"audio-analysis/0WdUHon5tYn2aKve13psfy"

The actual Julia wrapper function is duck typed, meaning that the 'track_id' argument type can be both String or SpTrackId. Numbers on the other hand, would produce an error.

function tracks_get_audio_analysis(track_id)
    tid = SpTrackId(track_id)
    spotify_request("audio-analysis/$tid")
end

Other API calls need more type information. Spotify understands the 'Spotify URI' ) format, where type is denoted by string prefixes. Such functions use a 'request body' to pass arguments. Request bodies often contain several arguments in a structure, for example a list or a dictionary. Request bodies comply with the JSON format.

So in a 'request body', we would represent 'track_id' like this:

julia> Spotify.JSON3.write(track_id)
"\"spotify:track:0WdUHon5tYn2aKve13psfy\""

All web API arguments are simple strings. Spotify.jl defines some types that have context-aware representations. Type names are Sp____Id.

Examples

Make an instance

julia> track_id = SpTrackId()        # output is colored
spotify:track:0WdUHon5tYn2aKve13psfy

In simple web API function calls like "audio-analysis" below, the type of the argument is obvious from the context; "spotify:track" is superfluous.

julia>"audio-analysis/$track_id"
"audio-analysis/0WdUHon5tYn2aKve13psfy"

The actual Julia wrapper function is duck typed, meaning that the 'track_id' argument type can be both String or SpTrackId. Numbers on the other hand, would produce an error.

function tracks_get_audio_analysis(track_id)
    tid = SpTrackId(track_id)
    spotify_request("audio-analysis/$tid")
end

Other API calls need more type information. Spotify understands the 'Spotify URI' ) format, where type is denoted by string prefixes. Such functions use a 'request body' to pass arguments. Request bodies often contain several arguments in a structure, for example a list or a dictionary. Request bodies comply with the JSON format.

So in a 'request body', we would represent 'track_id' like this:

julia> Spotify.JSON3.write(track_id)
"\"spotify:track:0WdUHon5tYn2aKve13psfy\""

All web API arguments are simple strings. Spotify.jl defines some types that have context-aware representations. Type names are Sp____Id.

Examples

Make an instance

julia> track_id = SpTrackId()        # output is colored
spotify:track:0WdUHon5tYn2aKve13psfy

In simple web API function calls like "audio-analysis" below, the type of the argument is obvious from the context; "spotify:track" is superfluous.

julia>"audio-analysis/$track_id"
"audio-analysis/0WdUHon5tYn2aKve13psfy"

The actual Julia wrapper function is duck typed, meaning that the 'track_id' argument type can be both String or SpTrackId. Numbers on the other hand, would produce an error.

function tracks_get_audio_analysis(track_id)
    tid = SpTrackId(track_id)
    spotify_request("audio-analysis/$tid")
end

Other API calls need more type information. Spotify understands the 'Spotify URI' ) format, where type is denoted by string prefixes. Such functions use a 'request body' to pass arguments. Request bodies often contain several arguments in a structure, for example a list or a dictionary. Request bodies comply with the JSON format.

So in a 'request body', we would represent 'track_id' like this:

julia> Spotify.JSON3.write(track_id)
"\"spotify:track:0WdUHon5tYn2aKve13psfy\""

All web API arguments are simple strings. Spotify.jl defines some types that have context-aware representations. Type names are Sp____Id.

Examples

Make an instance

julia> track_id = SpTrackId()        # output is colored
spotify:track:0WdUHon5tYn2aKve13psfy

In simple web API function calls like "audio-analysis" below, the type of the argument is obvious from the context; "spotify:track" is superfluous.

julia>"audio-analysis/$track_id"
"audio-analysis/0WdUHon5tYn2aKve13psfy"

The actual Julia wrapper function is duck typed, meaning that the 'track_id' argument type can be both String or SpTrackId. Numbers on the other hand, would produce an error.

function tracks_get_audio_analysis(track_id)
    tid = SpTrackId(track_id)
    spotify_request("audio-analysis/$tid")
end

Other API calls need more type information. Spotify understands the 'Spotify URI' ) format, where type is denoted by string prefixes. Such functions use a 'request body' to pass arguments. Request bodies often contain several arguments in a structure, for example a list or a dictionary. Request bodies comply with the JSON format.

So in a 'request body', we would represent 'track_id' like this:

julia> Spotify.JSON3.write(track_id)
"\"spotify:track:0WdUHon5tYn2aKve13psfy\""

All web API arguments are simple strings. Spotify.jl defines some types that have context-aware representations. Type names are Sp____Id.

Examples

Make an instance

julia> track_id = SpTrackId()        # output is colored
spotify:track:0WdUHon5tYn2aKve13psfy

In simple web API function calls like "audio-analysis" below, the type of the argument is obvious from the context; "spotify:track" is superfluous.

julia>"audio-analysis/$track_id"
"audio-analysis/0WdUHon5tYn2aKve13psfy"

The actual Julia wrapper function is duck typed, meaning that the 'track_id' argument type can be both String or SpTrackId. Numbers on the other hand, would produce an error.

function tracks_get_audio_analysis(track_id)
    tid = SpTrackId(track_id)
    spotify_request("audio-analysis/$tid")
end

Other API calls need more type information. Spotify understands the 'Spotify URI' ) format, where type is denoted by string prefixes. Such functions use a 'request body' to pass arguments. Request bodies often contain several arguments in a structure, for example a list or a dictionary. Request bodies comply with the JSON format.

So in a 'request body', we would represent 'track_id' like this:

julia> Spotify.JSON3.write(track_id)
"\"spotify:track:0WdUHon5tYn2aKve13psfy\""

All web API arguments are simple strings. Spotify.jl defines some types that have context-aware representations. Type names are Sp____Id.

Examples

Make an instance

julia> track_id = SpTrackId()        # output is colored
spotify:track:0WdUHon5tYn2aKve13psfy

In simple web API function calls like "audio-analysis" below, the type of the argument is obvious from the context; "spotify:track" is superfluous.

julia>"audio-analysis/$track_id"
"audio-analysis/0WdUHon5tYn2aKve13psfy"

The actual Julia wrapper function is duck typed, meaning that the 'track_id' argument type can be both String or SpTrackId. Numbers on the other hand, would produce an error.

function tracks_get_audio_analysis(track_id)
    tid = SpTrackId(track_id)
    spotify_request("audio-analysis/$tid")
end

Other API calls need more type information. Spotify understands the 'Spotify URI' ) format, where type is denoted by string prefixes. Such functions use a 'request body' to pass arguments. Request bodies often contain several arguments in a structure, for example a list or a dictionary. Request bodies comply with the JSON format.

So in a 'request body', we would represent 'track_id' like this:

julia> Spotify.JSON3.write(track_id)
"\"spotify:track:0WdUHon5tYn2aKve13psfy\""

Stored credentials

For the client credentials flow

A list of potentially available browsers, to be tried in succession if present

Default requested permissions are 'client-credentials'.

These permissions are not requested until the current scope is insufficient, or the user calls 'applyandwaitforimplicit_grant(;scopes)'

LOGSTATE mutable state

• .authorization::Bool
• .request_string::Bool
• .empty_response::Bool

Mutable flags for logging to REPL. Nice when making inline docs or new interfaces. This global can also be locally overruled with keyword argument to spotify_request.

For the 'Implicit grant flow'

Current stored credentials, access by spotcred()