View on GitHub

mod_spotify

A Spotify module for use with Corona SDK

Download this project as a .zip file Download this project as a tar.gz file

mod_spotify

A package for authentication and access to the Spotify Web API for use with Corona SDK.

The package containes two modules, one for the OAuth workflow, and the other is a "request" module to call the Spotify API. These modules reside in the spotify folder and should be left in that directory.

Setting up a Spotify app for mod_spotify

You will need to set up an app at the Spotify developer portal before you can start using the API in the mod. Most importantly, we need a client_id.

mod_spotify is using the Spotify Web API. You cannot stream music directly with this API. You can open a Spotify app, and send it a deep link, if its installed

  1. Log into your Spotify developer account (or register) at https://developer.spotify.com

  2. Click the My Apps navigation link

  3. Click the Create an app button

  4. Fill in the app details and click Create

  5. On the next page, scroll down and click Add Uri

  6. Enter: http://localhost/auth.html

  7. Click Add Uri again to add it. (huh?)

  8. Note the Client ID. You will use that in the mod.

  9. Make sure to click Save to update the changes.

  10. You're all done here!

Working with mod_spotify

Add the Spotify modules to your project:

local spotifyAuth = require('spotify.spotify_auth')
local spotifyApi = require('spotify.spotify_api')

spotify_auth module

spotify_auth.lua

The Spotify API uses OAuth2 for authentication, which means that the user must manually "whitelist" your application. This usually requires a visit to a web page for the user to log into the service and accept any special options your app requires (see 'scope' below).

The entire process is handled by the spotify_auth module. Leaving you (hopefully) with a user confirmed access token, which is then sent with each API request behind the scenes.

To start the OAuth workflow, which should happen towards the start of your app:

Set up a callback for the authorization

--hold the api instance
local spotify
-- Set up the callback
local function callback( table_result )
  if table_result.error then --error
    print('error', table_result.error)
  elseif table_result.token then --success
    --store the access token
    self.access_token = table_result.token
    --initialize the spotify_api
    --module with the access token.
    spotify = spotifyApi:init( self.access_token )
  end
end

Visualizing the output

You can pass true along with the access_token to enable auto table printing in the terminal, as the requests resolve.

-- Turn on auto output logging
spotify = spotifyApi:init( self.access_token, true )

You can also use the built-in command dump to manually output a table.

spotify.dump( api_tbl_data ) --prints to the terminal

Running the OAuth prompt

Prompt the user for the confirmation using an options table with some specific keys.

local options =
{
  client_id = 'YOUR_SPOTIFY_APP_CLIENT_ID',
  scope = 'user-library-read user-read-email'
  callback = callback
}

spotifyAuth:prompt( options )

Make sure to read up on the scoping options here. Scroll down a bit to the Scope list on the page.

Spotify Auth methods

spotifyAuth:prompt( options )

Prompt for confirmation. Returns access token, or error.

Options table keys


spotify_api module

spotify_api.lua

The spotify_api module provides a method of calling the Web REST API. You can view the Spotify API docs as a reference on putting together requests.

Search for an item (doc source)

local api_request =
{
  method = spotify.Get -- default, optional.
  path = 'search',
  params =
  {
    q = "A Tribe Called Quest",
    limit = 4,
    type = "track"
  },
  onResult = function( result_tbl )
    local media = result_tbl.items[1].images[1].url
  end
}
spotifyApi:request( api_request )

In the api_request above, the method key defaults to 'GET', so you can exclude it for any 'GET' requests (which is most). The params key will depend on each API function, and is a table of key/value pairs. See the Spotify Web API docs.

Figuring out the path parameter

On the Spotify endpoint reference page is a table of API actions. You can find the method from the Method column. In the Endpoint column is where you derive the path property for your request. As an example, the endpoints will look like so:

/v1/browse/categories

For your request path you only need everything after the "v1/". So for the endpoint above, you would use as the path parameter:

browse/categories

Building the params parameter

If you click on one of the doc links for an endpoint, you will be taken to a detail page that will commonly list additional query string modifiers you can add.

For example, the browse/categories options include country, locale, limit, etc. The query parameters vary for each endpoint.

Though output in JSON, you can also view the expected response structure on the API detail pages.

To add parameters to the query string, just build up an associative table.

local query_params =
{
  limit = 10,
  country = US
}

If the key names are exotic in any way -- contain spaces or the like -- then put the key name in quotes, and some brackets.

local query_params =
{
  limit = 10,
  country = "US",
  ["exotic key!"] = spotify.encode("a value with spaces")
}

Including data with 'POST' and 'PUT'

local req =
{
  path = 'browse/new-releases',
  body = '{"genre":"rock"}',
  method = spotify.Post
}

Any 'POST' or 'PUSH' actions take JSON data in the body. You can build these structures as tables first and then convert them.

local bt = { genre = "rock" }
local body = spotify.tbl2json( bt )

Some actions use both the body and params

local req =
{
  method = spotify.Put
  params = { username = "Martha" },
  body = spotify.tbl2json({ dogs = { 'Fred', 'Alice' }, reads = true })
}

You must specify the http method in every case, except 'GET'.

Setting up the onResult parameter

You need to set up a callback in onResult to retrieve any results.

local req =
{
  path = 'browse/new-releases',
  params = { limit = 1, country = 'US' },
  onResult = function( result_tbl )
    --output table to terminal
    spotify.dump( result_tbl )
  end
}

Send the Spotify Web API request

The results will be returned to the onResult handler.

Results are always returned as Lua tables.

spotify:request( req )

Spotify API methods

spotify:request( req_tbl )

Sends a request to Spotify

Request table keys

spotify.encode( url_str )

URL encode a string (escape)

spotify.decode( enc_url )

Decode a URL (unescape)

spotify.tbl2json( tbl )

Converts a Lua table to JSON string

spotify.json2tbl( json_str )

Converts JSON string to Lua table

spotify.dump( tbl )

Outputs a table in the terminal

Http method constants

spotify.Get

GET

spotify.Post

POST

spotify.Put

PUT

spotify.Delete

DELETE

You can use the method string in place of the constants in the request table.

:elephant: ©2015 C. Byerley - @develephant