gmusic

Documentation

Overview

Gmusic is a toy command line client for managing Google Play Music libraries.

Registering the client

Usage:

gmusic register id [name]

Gmusic must be registered with the user's Google Play account before it can be used to manage Google Play Music libraries. The registration process asks you to navigate to a special URL where you can grant access permissions for the Google Play Music Manager. Doing this gives you an authorization code, which is then input to gmusic to register it. Once gmusic has been registered, it creates a file called ".gmusic.json" in the user's home directory; other gmusic commands refer to this file for their access credentials.

The ID under which you register gmusic in your Google Play Music library needs to be unique on Google's side, so pick it reasonably randomly. Remember that there are limits to how many devices a single account can have authorized, with how many accounts a single device can be authorized, and how many devices one account can deauthorize in a year, so be careful in using this command.

Note that downloading tracks has been known to fail unless the ID is sufficiently MAC address-like. The exact threshold is unknown; perhaps the server only checks for a colon.

If a human-readable name under which to register gmusic is not given, it defaults to "gmusic".

Listing tracks

Usage:

gmusic list [-f format] [-p] [-t date]

List lists the tracks in the user's Google Play Music library in the following format:

6eaf9df8-8a2c-3845-a443-80a500e07cbd	桜花爛漫
448aa24d-18b7-38e0-a49a-3ab11db6f012	Hotel Nichifornia
64da27ed-721d-33ee-b70e-81cc84546590	Hold Your Sexy Arms Against Me
3a80d05a-58a1-3684-a154-fc046fcc4e6c	College Is Crazy
...

The -f flag can be used to specify an alternative format for the list, using the syntax of text/template. The default format is "{{.Id}}\t{{.Title}}\n". The struct passed to the template is:

type Track struct {
	Id          string
	Title       string
	Artist      string
	Album       string
	AlbumArtist string
	TrackNumber int
	TrackSize   int64

	// plus other, always-zero fields
}

The -p flag causes the listing to be limited to purchased or promotional tracks only.

The -t flag can be used to restrict the listing to tracks updated after the specified date, given as an RFC 3339 timestamp (up to microsecond precision). The default is "1970-01-01T00:00:00Z".

Downloading tracks

Usage:

gmusic download [id...]

Download downloads the tracks identified by the IDs to the current directory and prints the filenames they are saved under to standard output. Progress and error information is additionally written to standard error. If no IDs are given, a newline-separated list is read from standard input.

If a track fails to download, download moves on to the next one. The exit status is 0 only if all tracks downloaded successfully.

The filename under which each track is saved is generated server-side from the track's title and track number. Download clobbers existing files without asking, so be careful with it.

Uploading tracks

Usage:

gmusic upload [file...]

Upload uploads the named MP3 files to the user's Google Play Music library and prints their server-side IDs to standard output. Progress and error information is additionally printed to standard error. If no filenames are given, upload reads a newline-separated list from standard input.

If a file fails to upload, upload moves on to the next one. The exit status is 0 only if all tracks uploaded successfully.

Notes

Bugs

• There should probably be an option to disable diagnostic output in the download and upload commands.

• Gmusic does not actually detect and report an error on (most) non-MP3 files. All files are uploaded to Google Play, but only MP3 ones will be playable.