Repository files navigation

This code is licensed under the MIT license. The code is maintained onGitHub.

This is a reasonably complete implementation of the Pandora API in pure Pythonthat supports Python 3.5+. It contains a complete implementation of the coreradio features but does not implement account management or Pandora Plusfunctionality; pull requests adding that functionality are welcomed from anyoneneeding those features.

Keys or passwords for Pandora arenot provided in this repo, you'll have togo get thosefor yourself. Make something awesome with this library, don't abuse Pandora,that's not cool.

This projectis actively maintained but the author considers it to be bothstable and complete. There will be very few new changes initiated by the authoroutside of bug fixes and security updates.

If you run into a problem, file an issue and we'll respond. Pull requests fornew features and fixes will be reviewed and accepted if they meet our criteriafor stability, see below for contributing instructions.

This is the2.x series which supports only Python 3.8+. For older versionsof Python please use the1.x series. The1.x series is no longermaintained but pull requests to fix bugs are still welcomed.

This package uses semantic versioning. The API is guaranteed to be stablewithin a major version release. Please constrain your dependencies to majorversions. For example, to depend on version2.x use this line in yoursetup.pyinstall_requires:

pydora>=2,<3

Installing is as simple as using pip and running the built-in configurationcommand to create a~/.pydora.cfg file. If you already have aPianoBar config file Pydora will automatically usethat.

$ pip install pydora$ pydora-configure

On Ubuntu install vlc or vlc:

# apt-get install vlc

To install VLC on Mac OS X visit theVLC site to downloadVLC.app, then drag-and-dropthe bundle into your/Applications folder. Pydora will auto-detect this.

Thepydora player does not directly support audio output but instead reliesupon external audio output back-ends. The two supported back-ends are VLC andmpg123. The main difference between the two back-ends is the supported fileformats. VLC supports a vast array of codecs, including MP3 and AAC, the twoformats that Pandora uses. mpg123 on the other hand supports only MP3. As of2017 Pandora has started to prefer AAC files over MP3 which necessitates VLC.Thepydora player will try to auto-detect whatever player exists on yoursystem, preferring VLC, and will use that audio output back-end. If you noticea lot of skipping in a playlist consider installing VLC.

It is also possible to remotely control a copy of VLC running on anothermachine if you're unable or unwilling to install Pydora on your playbackmachine. To do this start VLC on the remote machine with therc-host optionset. For example:

vlc -I rc --advanced --rc-host=0.0.0.0:1234

Once VLC is running start Pydora with thevlc-net option and specify theremote host and port that VLC is listening on. For example:

pydora --vlc-net 192.168.0.12:1234

Pydora will now send all audio playback requests to the remote VLC. It doesthis using a text control protocol; all audio data is streamed directly fromthe internet to VLC and is not passed over the Pydora control channel. Becauseof this it is possible for the control channel to run over a very low bandwidthconnection.

Note: VLC doesn't provide any security so anyone on the network will beable to control VLC. It is generally safer to bind VLC to127.0.0.1 and usesomething like SSH forwarding to securely forward the port to a remote host butthat's outside of the scope of this README.

Included ispydora, a simple Pandora stream player that runs at the commandline. It requires that mpg123 or VLC be installed with HTTP support as well asa settings file (example below) located in~/.pydora.cfg. Alternatively anenvironment variablePYDORA_CFG can point to the path of the config file.

The player only supports basic functionality for now. It will display a stationlist, allow listening to any station, basic feedback and bookmarking are alsosupported. The player starts an mpg123 or VLC process in remote control modeand feeds commands to it. It does not download any music but rather streamsthem directly from Pandora.

When playing the following keys work (press enter afterwards):

• n - next song
• p - pause or resume song
• s - station list (stops song)
• d - thumbs down track
• u - thumbs up track
• b - bookmark song
• a - bookmark artist
• S - sleep song
• Q - quit program
• vu - volume up
• vd - volume down
• ? - display help

Note: volume control is currently only supported with the VLC back-end.

The built-inpydora-configure script can be run to create a configurationfile automatically if you don't already have one. This will download the keysfrom the link below and pick a suitable one when writing the config file. Ifyou want to create the config file manually the format is:

[api]api_host = hostnameencryption_key = keydecryption_key = keyusername = partner usernamepassword = partner passworddevice = keydefault_audio_quality = mediumQuality[user]username = your usernamepassword = your password

default_audio_quality

Default audio quality to request from the API; can be one of lowQuality,mediumQuality (default), or highQuality. If the preferred audio qualityis not available for the device specified, then the next-highest bit-ratestream that Pandora supports for the chosen device will be used.

The Pydora distribution contains two python packages. Thepandora packageis the API for interacting with the Pandora service. Thepydora package isa very small reference implementation of using the API to drive a command lineplayer. If you're interested in the command line skip this section and readInstalling below to get started.

The easiest way to get started is by using thepandora.clientbuilderpackage. This package contains a set of factories that can be used to build aPandora client with some configuration. The classes in the package that end inBuilder are the factories and the rest of the classes are implementationdetails. All of the builders will return an instance ofpandora.client.APIClient that is completely configured and ready for use inyour program.

If you have an existing program and would like to connect to Pandora theeasiest way is to use theSettingsDictBuilder class like so:

client = SettingsDictBuilder({    "DECRYPTION_KEY": "see_link_above",    "ENCRYPTION_KEY": "see_link_above",    "PARTNER_USER": "see_link_above",    "PARTNER_PASSWORD": "see_link_above",    "DEVICE": "see_link_above",}).build()client.login("username", "password")

At this point the client is ready for use, seepandora.client.APIClient fora list of methods that can be called. All responses from the API will returnPython objects from thepandora.models.pandora package or raise exceptionsfrompandora.errors

For a more functional example look at the filepydora/player.py which showshow to use the API in a simple command line application.

If you're interested in the underlying API or need to download the keysyourself you can find more details at the links below. This documentation iscommunity maintained and not official.

• API Spec
• Partner Keys

SeeCONTRIBUTING

Thanks to the contributors who make Pydora possible by adding features andfixing bugs. List is organized by date of first contribution.

• Mike Crute (@mcrute)
• John Cass (@jcass77)
• Thomas Weißschuh (@t-8c)
• Skybound1 (@Skybound1)
• Hugo (@hugovk)
• mspencer92 (@mspencer92)
• enzu.ru (@enzuru)
• Théophile (@theophileds)