gmusic-ui.js

Browser-side JS library for controlling Google Music through UI manipulation.

gmusic-ui.js is not created by, affiliated with, or supported by Google Inc.

Getting Started

It's important to note the gmusic-ui.js depends on gmusic.js in order to operate correctly

npm

Install the module with: npm install gmusic.js gmusic-ui.js

Once installed, add it to your HTML and access it via window.GMusic.

<script>
  require('gmusic.js')
  require('gmusic-ui.js')
  window.gmusic = new window.GMusic(); // Our Google Music API
</script>

Vanilla

If you are not using a package manager, download the latest script at:

https://raw.githubusercontent.com/gmusic-utils/gmusic-ui.js/master/dist/gmusic-ui.min.js

Then, add it to your HTML and access it via window.GMusic.

<script src="gmusic.min.js"></script>
<script src="gmusic-ui.min.js"></script>
<script>
  window.gmusic = new window.GMusic(window); // Our Google Music API
</script>

Documentation

gmusic-ui.js extends the GMusic constructor, window.GMusic

Data Structures

Album

{
  "id": String,           // Unique ID for this album
  "name": String,         // The name of the album
  "artist": String,       // The name of the artist for the album
  "albumArt": String,     // URL to the albumArt for this album
}

Artist

{
  "id": String,           // Unique ID for this artist
  "name": String,         // The name of the artist
  "image": String,        // URL to an image of this artist
}

Playlist

{
  "id": String,           // Unique ID for this playlist
  "name": String,         // User defined name for this playlist
  "tracks": Track[],      // An array of Track objects that make up the playlist
}

SearchResults

{
  "searchText": String,   // The text the user searched for to get these results
  "bestMatch": {
    "type": String,       // The type of result that is best.  One of "album", "artist" or "track"
    "value": Album | Artist | Track
  }
  "albums": Album[],      // An array of albums that are part of these search results
  "artists": Artist[],    // An array of artists that are part of these search results
  "tracks": Track[],      // An array of tracks taht are part of these search results
}

new GMusic(window)

Constructor for a new Google Music API.

• window - Object - The global window object

You can read up on the namespaces and methods that gmusic natively offers over in the gmusic.js README

Below are the namespaces and methods that gmusic-ui adds to GMusic

Playlists

playlists.getAll()

Retrieves a list of all the playlists in the users GPM library

Returns:

• retVal Playlist[] - An array of Playlist objects

playlists.play(playlist)

Navigates to the given playlist and plays it immediately

• playlist Playlist - A Playlist object returned from getAll()

Returns:

• retVal Promise - A promise that resolves when the playlist starts playing. This promise can be rejected so you need to handle any errors with .catch

playlists.playWithTrack(playlist, track)

Navigates to the given playlist and plays it immediately starting at the given track

• playlist Playlist - A Playlist object returned from getAll()
• track Track - A Track object from the tracks property of the supplied playlist

Returns:

• retVal Promise - A promise that resolves when the track starts playing. This promise can be rejected so you need to handle any errors with .catch

Queue

queue.clear()

Clears the current queue

queue.getTracks()

Retrieves a list of all the tracks in the users current queue

Returns:

• retVal Track[] - An array of Track objects

queue.playTrack(track)

Attempts to play a given track in the queue. If this track is not in the queue an error will be thrown

• track Track A Track object returned from getTracks()

Returns:

• retVal Promise - A promise that resolves when the track starts playing. This promise can be rejected so you need to handle any errors with .catch

Search

search.getCurrentResults()

Retrieves a SearchResults object representing the current search results. Will throw an error if the user is not currently searching

Returns:

• retVal SearchResults - An object of the structure of a SearchResults object

search.getSearchText()

Retrieves the current string that the user is searching for or the most recent string the user searched for. Basically whatever is in the search input field at the moment.

Returns:

• retVal String - The value of the search input field

search.isSearching()

Determines if the user is currently searching or not

Returns:

• retVal Boolean - True if the user is searching, False otherwise

search.performSearch(text)

Immediately triggers a new search for the given text

• text String A word of sequence of words to search for

Returns:

• retVal Promise - A promise that will resolve with the results of the search you just performed. The promise will be rejected with a timeout error if the search takes too long.

search.playResult(result)

Immediately attempts to play the given result. If we fail to play the given result an error will be thrown.

• result Album | Artist | Track - An object returned from getResults() that you wish to play

Hooks

Hooks are bound the same way as the gmusic.js hooks.

###.on('change:playlists') Triggers when the content of any playlist or the list of playlists changes in any way.

gmusic.on('change:playlists', function (playlists) {
})

• playlists Playlist[] - A list of Playlist objects

###.on('change:queue') Triggers when the contents of the queue is changes in any way

gmusic.on('change:queue', function (queue) {
})

###.on('change:search-results') Triggers when a new search is performed and the results change

gmusic.on('change:search-results', function (newResults) {
})

• queue Track[] - A list of Track objects

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via npm run lint and test via npm test.

Testing

Currently there is no testing framework. We should probably implement the GMusic.js testing library in this repo aswell