Subscene Build Status

Ruby API Client for

Introduction is a very complete and reliable catalog of subtitles. If you're reading this you probably know they don't have an API.

This gem will help you communicate with easily.


Add this line to your application's Gemfile:

gem 'subscene'

And then execute:

$ bundle

Or install it yourself as:

$ gem install subscene

Searching handles two kinds of searches:

  1. Search by Film or TV Show 'title'

    e.g. "The Big Bang Theory", "The Hobbit", etc.

  2. Search for a particular 'release'

    e.g. "The Big Bang Theory s01e01" or "The Hobbit HDTV"

There are certain keywords that trigger one search or the other, this gem initially will support the second type (by release) so make sure to format your queries properly.


The search method will return subtitles that match the query.'The Big Bang Theory s01e01')# => [#<Subscene::SubtitleResult @attributes={:id=>"136037", :name=>"The.Big.Bang.Theory..",
      #<Subscene::SubtitleResult @attributes={:id=>"138042", :name=>"The Big Bang.."]

Once you get the results, you can iterate over them and review your options.

The information within these results is limited to what the search reveals:

You can obtain additional information by finding the id.

Subscene.find( # or Subscene.find(151582) directly
=> #<Subscene::Subtitle @id="151582", @name="Fringe.S01E01.DVDSCR.XviD-MEDiEVAL-EN", @lang="English", @user="Jap", @user_id="20904", @comment="Has no comment.", @rating="8", @downloads="9,549", @framerate="Not available", @created_at="6/18/2008 3:09 PM", @download_url="/subtitle/download?mac=yoPjbFZ9WFbUmWTWpOvaGbXDYN2b4yBreI8TJIBfpdynT-4hzba446VvrVyxamBM0", @hearing_impaired=false>

Language Preferences

You can set the language id for the search filter. Ids can be found at Maximum 3, comma separated.

# Examples
Subscene.language = 13 # English"...") # Results will be only English subtitles
Subscene.language = "13,38" # English, Spanish


  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