# Usage

## Installation

Use pip: `$ pip install gmusicapi`.

To install the yet-to-be-released development version, use `$ pip install git+https://github.com/simon-weber/gmusicapi.git@develop#egg=gmusicapi`.

If you’re going to be uploading music, you’ll likely need avconv or ffmpeg installed and in your system path, along with at least libmp3lame:

> - Linux
>   - Use your distro’s package manager: e.g `$ sudo apt-get install libav-tools libavcodec-extra-53` (ffmpeg requires extra steps on Debian/Ubuntu).
>   - Download pre-built binaries of avconv or ffmpeg and edit your path to include the directory that contains avconv/ffmpeg.
> - Mac
>   - Use Homebrew to install libav (avconv) or ffmpeg.
> - Windows
>   - Download pre-built binaries of avconv or ffmpeg and edit your path to include the directory that contains avconv.exe/ffmpeg.exe.
> - Google App Engine
>   - See this thread for instructions.

The only time avconv or ffmpeg is not required is when uploading mp3s without scan-and-match enabled.

If you need to install avconv/ffmpeg from source, be sure to use `$ ./configure --enable-gpl --enable-nonfree --enable-libmp3lame`.

## Quickstart

There are two supported client classes based on different Google apis.

The `Mobileclient` uses the Android app’s apis to handle library management and playback.

The `Musicmanager` uses the desktop Music Manager’s apis to handle uploading and downloading.

Both have similar command-line OAuth2 interfaces for logging in. For example:

    from gmusicapi import Musicmanager

    mm = Musicmanager()
    mm.perform_oauth()

This only needs to be run once, and if successful will save a refresh token to disk. Then, future runs can start with:

    from gmusicapi import Musicmanager

    mm = Musicmanager()
    mm.login()  # currently named oauth_login for the Mobileclient

If you need both library management and uploading, just create multiple client instances.

There is also the `Webclient`, which is uses the webapp’s apis to handle similar tasks to the Mobileclient. It is not tested nor well supported, and requires providing full account credentials to use. Avoid it if possible.

The reference section has complete information on all clients:

- Client Interfaces
  - Webclient Interface
  - Mobileclient Interface
  - Musicmanager Interface