Hypem Ruby Gem #

This is an unoffical Ruby gem for the Hype Machine read-only API. It currently only supports Ruby >= 1.9.2.

The Playlist object is the root of the Hypem API. Each Playlist has an array of Hypem::Track's accessed via the tracks attribute. Pagination is supported with the .next_page and .prev_page, page(num) methods.

General playlists can be accessed using the following methods. The last argument to each method is the desired page (default 1).

• Hypem.playlist.artist('artist_name') --- latest tracks from a given artist

• Hypem.playlist.blog('blog_name') --- latest tracks from a given blog name

• Hypem.playlist.search('query_string') --- tracks matching string

• Hypem.playlist.tags(['tag_name','electro','indie']) --- tracks matching tags. The API warns against combining too many different tags

• Hypem.playlist.popular --- the most popular tracks over a certain timeframe or set. It accepts the following filters:

  • '3day' default --- most popular over last 3 days
  • :lastweek --- most popular over last week
  • :noremix --- most popular non-remixed tracks over last 3 days
  • :artists --- most popular artists' tracks over last 3 days
  • :twitter --- most popular tweeted tracks over last 3 days

• Hypem.playlist.latest --- the latest posted tracks. It accepts the following filters:

  • :all default --- all tracks, regardless of repost status
  • :fresh --- only first posted tracks
  • :noremix --- only non-remixed tracks
  • :remix --- only remixed tracks

• Hypem.playlist.new_from_tracks([hypem_track1,hypem_track2]) --- create a custom playlist from an array of Hypem::Track's

Users can be accessed via Hypem.user('username') and have various methods:

• user.get_profile updates the user object with the following attributes: full_name, location, image_url, followed_users_count, followed_items_count, followed_sites_blog, and followed_queries_count

• user.friends retrieves the user's friends as an array of Hypem::User objects

• user.favorite_blogs retrieves the user's favorite blogs as an array of Hypem::Blog objects

Hypem::User offers several methods for accessing a particular user's personalized playlists:

• user.loved_playlist --- a user's loved tracks

• user.obsessed_playlist --- a user's obsessed tracks

• user.feed_playlist --- a user's tracks from all followed entities

• user.friends_favorites_playlist --- a user's friends' favorited tracks

• user.friends_history_playlist --- tracks from a user's friends' listening histories

Blogs can be retrieved using a blog's unique id via Hypem.blog(1234) and have the following methods:

• blog.get_info -- retrieves extended information about a blog and sets blog_image, blog_image_small, first_posted, followers, last_posted, site_name, site_url, total_tracks, and id

Tracks can be initialized using a known media_id via Hypem.track('media_id') and synced using the get method on any instance. Depending on the playlist type, some tracks may have more detailed attributes than other.

An example track object inspection is as follows:

@media_id="1jsw9",
@artist="Hot Chip",
@title="Flutes",
@date_posted=#<DateTime: 2012-06-08T16:57:00-07:00 ((2456087j,86220s,0n),-25200s,2299161j)>,
@site_id=16116,
@site_name="the untz and the indie",
@post_url="http://theuntzandtheindie.com/2012/06/08/hot-chip-party/",
@post_id=1835105,
@loved_count=9050,
@posted_count=33,
@thumb_url="http://static-ak.hypem.net/images/albumart0.gif",
@thumb_url_large="http://static-ak.hypem.net/images/blog_images/16116.png",
@time=425,
@description="Today’s Indie: If I Was Your Girlfriend (Hot Chip Cover) / Prince /// Motion Sickness / Hot Chip /// Flutes / Hot Chip So the indie extraordinaire and goddess of all things awesome is out of town up in the Pac NW gettin silly and listening to dAHnce music",
@itunes_link="http://hypem.com/go/itunes_search/Hot%20Chip"

The people who liked a track can be retrieved via Hypem::TrackFavorites('trackid') or track.favorites and synced using the get method.

Their pagination is supplied via the same methods as the Hypem::Playlist ones, and they also accept the desired page as the last argument at initialization : Hypem::TrackFavorites('trackid', page)

The Hypem::Users present in each page can be retrieved via the users instance method

• Blogs with given tag
• Authenticated Requests
• Favorite a track
• Log Playback