{"id":21201674,"url":"https://github.com/oleander/torrents","last_synced_at":"2025-07-10T06:31:53.491Z","repository":{"id":1388174,"uuid":"1363856","full_name":"oleander/Torrents","owner":"oleander","description":"Search and download torrents from your favourite bittorrent tracker using Ruby 1.9","archived":false,"fork":false,"pushed_at":"2011-12-27T17:50:29.000Z","size":319,"stargazers_count":25,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-03-15T14:10:46.683Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/oleander/Torrents","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oleander.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-02-14T03:43:29.000Z","updated_at":"2024-01-14T08:40:18.000Z","dependencies_parsed_at":"2022-07-18T16:52:42.868Z","dependency_job_id":null,"html_url":"https://github.com/oleander/Torrents","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2FTorrents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2FTorrents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2FTorrents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2FTorrents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oleander","download_url":"https://codeload.github.com/oleander/Torrents/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225622846,"owners_count":17498168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T20:10:28.319Z","updated_at":"2024-11-20T20:10:29.094Z","avatar_url":"https://github.com/oleander.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Torrents\n\nSearch and download torrents from your favorite bittorrent tracker using **Ruby 1.9**.\n\nDownload and get information like:\n\n- Subtitles, english and swedish.\n- Movie information (if the torrent is a movie), actors, grade, original title, length, trailers and so on.\n- A direct download link to the torrent.\n- [IMDB](http://imdb.com) link\n\n## This version is no longer maintained\n\nVersion 1.0 is no longer maintained.\nI might release version 2.0 in the future.\n\n## Which trackers are implemented at the moment?\n\n### Open trackers\n\n- [The Pirate Bay](http://thepiratebay.org/)\n\n### Closed trackers\n\n- [TTI](http://tti.nu/)\n- [Torrentleech](http://www.torrentleech.org/)\n\n## How to use\n\n### Search for torrents\n\n```` ruby\nTorrents.the_pirate_bay.search(\"chuck\").results\n````\n\n### List recent torrents\n\n```` ruby\nTorrents.the_pirate_bay.results\n````\n\n### List recent torrents - with category\n\n```` ruby\nTorrents.the_pirate_bay.category(:movies).results\n````\n\n### Specify a page\n\nThe `page` method can be places anywhere before the `results` method.\n\nIt starts counting from `1` and goes up, no matter what is used on the site it self.\n\n```` ruby\nTorrents.the_pirate_bay.page(6).results\n````\n\n### Specify some cookies\n\nSome trackers requires cookies to work, even though [The Pirate Bay](http://thepiratebay.org/) is not one of them.\n\n```` ruby\nTorrents.the_pirate_bay.cookies({\n  user_id: \"123\", \n  hash: \"c4656002ce46f9b418ce72daccfa5424\"\n}).results\n````\n\n### Step through torrents\n\nHere is an example of how to step through the 10 first pages.\n\n```` ruby    \ntorrents = Torrents.the_pirate_bay.step\n10.times { torrents.results }\n````\n\nYou just add the step method and it will increment `page` everytime you apply the `results` method.\n\n## What methods to work with\n\n### The results method\n\nAs soon as you apply the `results` method on the query it will try to execute your request.\nIf you for example want to activate the debugger, define some cookies or specify a page, then you might do something like this.\n\n```` ruby      \nTorrents.the_pirate_bay.page(5).debug(true).cookies(:my_cookie =\u003e \"value\").results\n````\n\nIt will return a list of `Container::Torrent` object if the request was sucessfull, otherwise an empty list.\n\n### The find_by_details method\n\nIf you have access to a single details link and want to get some useful data from it, then `find_by_details` might fit you needs.\n\nThe method takes the url as an argument and returns a single `Container::Torrent` object.\n\n```` ruby\nTorrents.the_pirate_bay.find_by_details(\"http://thepiratebay.org/torrent/6173093/\")\n````\n\n## What data to work with\n\n### The Container::Torrent class\n\nThe class has some nice accessors that might be useful.\n\n- **title** (String) The title.\n- **details** (String) The url to the details page.\n- **seeders** (Fixnum) The amount of seeders.\n- **dead?** (Boolean) Check to see if the torrent has no seeders. If it has no seeders, then `dead?` will be true.\n- **torrent** (String) The url. This should be a direct link to the torrent.\n- **id** (Fixnum) An unique id for the torrent. The id is only unique for this specific torrent, not all torrents.\n- **tid** (String) The `tid` method, also known as `torrent id` is a *truly* unique identifier for all torrents. It is generated using a [MD5](http://sv.wikipedia.org/wiki/MD5) with the torrent domain and the `id` method as a seed.\n- **torrent_id** (String) The same as the `tid` method.\n- **imdb** (String) The imdb link for the torrent, if the details view contains one. \n- **imdb_id** (String) The imdb id for the torrent, if the details view contain one. Example: tt0066026.\n- **subtitle** ([Undertexter](https://github.com/oleander/Undertexter)) The subtitle for the torrent. Takes one argument, the language for the subtitle. Default is `:english`. Read more about it [here](https://github.com/oleander/Undertexter).\n- **movie** ([MovieSearcher](https://github.com/oleander/MovieSearcher)) Read more about the returned object at the [MovieSearcher](https://github.com/oleander/MovieSearcher) project page.\n\n**Note:** The `seeders`, `movie`, `subtitle`, `imdb_id` and `ìmdb` method will do another request to the tracker, which means that it will take a bit longer to load then the other methods.\n\n## What cookies to pass\n\nHere is an example\n\n```` ruby\nTorrents.torrentleech.cookies({\n  :member_id =\u003e \"123\", \n  :pass_hash =\u003e \"value\", \n  :PHPSESSID =\u003e \"value\"\n}).results \n````\n\nAll values you pass to `cookies` must be of type string, like in the example above.\n\n- Torrentleech\n  - member_id\n  - pass_hash\n  - PHPSESSID\n  - tluid\n  - tlpass\n- TTI\n  - hass\n  - pass\n  - uid\n  \n**General note:** The cookies you pass might be browser and IP-adress sensitive. Which means that it might only work in the current browser using the current Internet connection.\n\n**Torrentleech note:** Remember to check the *Remember Me* checkbox before using your browsers cookies.\n\n## Error handling\n\nI decided in the beginning of the project to rescue parse errors during the runtime and instead print them as warnings.\n\n### Why? - Lack of good selectors\n\nThe trackers parser, [this](https://github.com/oleander/Torrents/blob/master/lib/torrents/trackers/the_pirate_bay.rb) one for example, isn't always returning the right data. \n\nDue to the lack of useful CSS selectors on the given tracker. It returns 32 rows, the first and the last containing the header and the footer of the table.\nThe unwanted results will be thrown away by the [validator](https://github.com/oleander/Torrents/blob/master/lib/torrents/container.rb#L141), but may raise errors during the run time.\nThe easiest way to solve it was to just isolate the tracker, if it raised an error we return nil.\n\n### Get the error messages\n\nYou can read errors in two ways.\n\nActivate the debugger by adding the `debug` method to your query. The errors will be printed as warnings in the console.\n\n```` ruby  \nTorrents.the_pirate_bay.debug(true).results\n````\n\nRequest a list of errors using the `errors` method.\n\n```` ruby\np Torrents.the_pirate_bay.errors\n# =\u003e [\"...undefined method `attr' for nil:NilClass\u003e...\", \"32 torrents where found, 2 where not valid\", \"...\"]\n````\n\n## How do access tracker X\n\nHere is how to access an implemented tracker.\nThe first static method to apply is the name of the tracker in lower non camel cased letters.\n\nThe Pirate Bay becomes `the_pirate_bay`, TTI becomes `tti` and Torrentleech `torrentleech`.\n\nHere is an example.\n\n```` ruby\nTorrents.torrentleech.cookies({:my_cookie =\u003e \"value\"}).results \n````\n\nTake a look at the [tests](https://github.com/oleander/Torrents/tree/master/spec/trackers) for all trackers to get to know more.\n\n## Add you own tracker\n\nI'm about to write a wiki that describes how to add you own site.\nUntil then, take a look at the parser for [The Pirate Bay](https://github.com/oleander/Torrents/blob/master/lib/torrents/trackers/the_pirate_bay.rb).\n\nAll heavy lifting has already been done, so adding another tracker should be quite easy.\n\nI'm using [Nokogiri](http://nokogiri.org/) to parse data from the site, which in most cases means that you don't have to mess with regular expressions.\n\nDon't know Nokogiri? Take a look at [this](http://railscasts.com/episodes/190-screen-scraping-with-nokogiri) awesome screen cast by [Ryan Bates](https://github.com/ryanb). \n    \n### The short version\n\n1. Create your own fork of the project.\n2. Create and implement a tracker file inside the [tracker directory](https://github.com/oleander/Torrents/tree/master/lib/torrents/trackers).\n3. Add a cached version of the tracker [here](https://github.com/oleander/Torrents/tree/master/spec/data). **Note:** Remember to remove sensitive data from the cache like user name and uid.\n4. Add tests for it, [here](https://github.com/oleander/Torrents/blob/master/spec/trackers/the_pirate_bay_spec.rb) is a skeleton for the Pirate Bay class to use as a start.\n5. Add the tracker to the readme.\n6. Do a pull request, if you want to share you implementation with the world.\n\nYou don't have to take care about exceptions, *Torrents* does that for you.\n\n## Disclaimer\n\nBefore you use *Torrents* make sure you have permission from the tracker in question to use their data.\n\n## How do install\n\n    [sudo] gem install torrents\n    \n## How to use it in a rails 3 project\n\nAdd `gem 'torrents'` to your Gemfile and run `bundle`.\n\n## Requirements\n\n*Torrents* is tested in OS X 10.6.6 using Ruby 1.9.2.\n\n## License\n\n*Torrents* is released under the MIT license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foleander%2Ftorrents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foleander%2Ftorrents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foleander%2Ftorrents/lists"}