Pandoru

Pandoru is a Ruby port of the Python pydora library, providing a comprehensive client for the unofficial Pandora music streaming API. This gem allows you to interact with Pandora programmatically to manage stations, get playlists, search for music, and control playback.

⚠️ Note: This is an unofficial API client. Use at your own risk and respect Pandora's terms of service.

---

Features

• Station Management: Get station lists, create/delete stations, rename stations
• Playlist Access: Retrieve playlists with track metadata and audio URLs
  
• Music Search: Search for songs, artists, and albums
• User Interaction: Thumbs up/down, bookmarks, sleep songs
• Feedback Management: Add/remove track feedback
• Station Seeds & Genome Traits: Inspect a station's seed artists/songs/genres and a track's Music-Genome focus traits (explain_track)
• Genre Exploration: Browse and create stations from genre seeds
• Multiple Audio Qualities: Support for low, medium, and high quality audio streams
• Ruby Idioms: Built with Ruby best practices and idiomatic patterns

---

Installation

Add this line to your application's Gemfile:

gem 'pandoru'

Then execute:

bundle install

Or install it yourself as:

gem install pandoru

---

Usage

Configuration

Pandoru requires Pandora partner credentials to function. You can configure these in several ways:

1. Using a Configuration Hash

require 'pandoru'

# Note: These are example credentials - you need real ones
settings = {
  "PARTNER_USER" => "your-partner-user",
  "PARTNER_PASSWORD" => "your-partner-password", 
  "DEVICE" => "your-device-type",
  "DECRYPTION_KEY" => "your-decryption-key",
  "ENCRYPTION_KEY" => "your-encryption-key"
}

client = Pandoru::ClientBuilder.from_settings_hash(settings)
client.login("your_email@example.com", "your_password")

2. Using Configuration Files

Pandoru supports both pydora-style and pianobar-style configuration files:

# From a pydora config file
client = Pandoru::ClientBuilder.from_config_file("~/.pydora.cfg")

# From a pianobar config file  
client = Pandoru::ClientBuilder.from_config_file("~/.config/pianobar/config")

Basic Operations

Managing Stations

# Get all user stations
stations = client.get_station_list

# Create a new station from search results
search_results = client.search("Radiohead")
station = client.create_station(search_token: search_results.first.music_token)

# Rename a station
client.rename_station(station.token, "My Radiohead Station")

# Delete a station
client.delete_station(station.token)

Working with Playlists

# Get a playlist from a station
playlist = client.get_playlist(station.token)

playlist.each do |track|
  puts "#{track.artist_name} - #{track.song_name}"
  puts "Audio URL: #{track.audio_url}"

  # Rate the track
  track.thumbs_up if track.allow_feedback

  # Bookmark the song or artist
  track.bookmark_song
  track.bookmark_artist
end

Searching for Music

# Search for music
results = client.search("The Beatles", include_near_matches: true)

results.songs.each do |song|
  puts "Song: #{song.song_name} by #{song.artist_name}"
end

results.artists.each do |artist|
  puts "Artist: #{artist.artist_name}"
end

Managing Bookmarks

# Get user bookmarks
bookmarks = client.get_bookmarks

bookmarks.song_bookmarks.each do |bookmark|
  puts "Bookmarked song: #{bookmark.song_name} by #{bookmark.artist_name}"
end

bookmarks.artist_bookmarks.each do |bookmark|
  puts "Bookmarked artist: #{bookmark.artist_name}"
end

Advanced Features

Genre Stations

# Browse genre stations
genre_stations = client.get_genre_stations

genre_stations.categories.each do |category|
  puts "Category: #{category}"
  genre_stations.stations_for_category(category).each do |station|
    puts "  Station: #{station.name}"
  end
end

Audio Quality

# Set default audio quality when creating client
client = Pandoru::ClientBuilder.from_settings_hash(settings.merge(
  "AUDIO_QUALITY" => "highQuality"  # or "mediumQuality", "lowQuality"
))

# Get specific quality audio URL for a track
track = playlist.first
high_quality_url = track.audio_url("highQuality")
medium_quality_url = track.audio_url("mediumQuality")  
low_quality_url = track.audio_url("lowQuality")

Error Handling

begin
  client.login("user@example.com", "password")
rescue Pandoru::Errors::InvalidUserLogin
  puts "Invalid username or password"
rescue Pandoru::Errors::PandoraException => e
  puts "Pandora API error: #{e.message} (Code: #{e.code})"
end

---

API Reference

Client Classes

• Pandoru::Client::APIClient - High-level API client with all Pandora operations
• Pandoru::Client::BaseAPIClient - Lower-level client for advanced usage

Models

• Pandoru::Models::Station - Represents a Pandora station
• Pandoru::Models::StationList - Collection of user stations
  
• Pandoru::Models::Playlist - Collection of playlist items
• Pandoru::Models::PlaylistItem - Individual track in a playlist
• Pandoru::Models::SearchResult - Search results container
• Pandoru::Models::BookmarkList - User's bookmarked songs and artists

Client Builders

• Pandoru::ClientBuilder.from_settings_hash(hash) - Create client from settings hash
• Pandoru::ClientBuilder.from_config_file(path) - Create client from config file
• Pandoru::ClientBuilder.default_client() - Create client with default settings

---

Architecture

Pandoru is architected similarly to the original pydora library:

• Transport Layer: Handles HTTP communication and encryption/decryption
• Client Layer: Provides high-level API methods
• Models Layer: Represents Pandora data structures with Ruby idioms
• Builders Layer: Factory classes for creating configured clients

The Ruby port maintains compatibility with pydora's API while providing Ruby-style interfaces and error handling.

---

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt.

To install this gem onto your local machine, run bundle exec rake install.

---

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/TwilightCoders/pandoru.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

---

License

The gem is available as open source under the terms of the MIT License.

---

Acknowledgments

This Ruby gem is a port of the excellent pydora Python library by Mike Crute and contributors. All credit for the original API reverse engineering and design goes to the pydora project.

Disclaimer

⚠️ This project is not affiliated with or endorsed by Pandora Media, Inc. Use of this library may violate Pandora's Terms of Service. Use at your own risk.