{"id":13644062,"url":"https://github.com/oz/osdb","last_synced_at":"2025-03-17T21:30:56.975Z","repository":{"id":14610370,"uuid":"17327625","full_name":"oz/osdb","owner":"oz","description":"Golang client for Opensubtitles.org","archived":false,"fork":false,"pushed_at":"2022-12-14T17:57:51.000Z","size":9666,"stargazers_count":70,"open_issues_count":2,"forks_count":20,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-02T01:22:13.299Z","etag":null,"topics":["go","opensubtitles","osdb"],"latest_commit_sha":null,"homepage":"https://github.com/oz/osdb","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-02T00:22:40.000Z","updated_at":"2024-07-12T12:37:57.000Z","dependencies_parsed_at":"2023-01-13T20:15:18.742Z","dependency_job_id":null,"html_url":"https://github.com/oz/osdb","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oz%2Fosdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oz%2Fosdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oz%2Fosdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oz%2Fosdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oz","download_url":"https://codeload.github.com/oz/osdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221700542,"owners_count":16866085,"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":["go","opensubtitles","osdb"],"created_at":"2024-08-02T01:01:56.992Z","updated_at":"2024-10-27T15:47:18.262Z","avatar_url":"https://github.com/oz.png","language":"Go","funding_links":["https://liberapay.com/oz/donate"],"categories":["Go"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/oz/osdb.svg?branch=master)](https://travis-ci.org/oz/osdb)\n[![Coverage Status](https://coveralls.io/repos/github/oz/osdb/badge.svg)](https://coveralls.io/github/oz/osdb)\n[![Donate using Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/oz/donate)\n\nA Go client for [OpenSubtitles](http://opensubtitles.org/).\n\nThis project allows you to search and download subtitles from OpenSubtitles. It\ncomes both as a command-line program, and a library that you can use from other\nprograms.\n\nIf you need to search or download subtitles, then you should find what you need\nfrom the latest releases, otherwise the [TODO](https://github.com/oz/osdb#todo)\nsection highlights what remains to be done regarding API coverage.\n\n\n# Installation\n\nIf you want to compile the CLI interface for OpenSubtitles, then install the\nlatest [Go](http://golang.org) release, and run:\n\n```\ngo get github.com/oz/osdb \u0026\u0026 go install github.com/oz/osdb/cmd/osdb\n```\n\nProvided that you setup your Go environment correctly, you now have a basic\n`osdb` command to interact with OpenSubtitles' API.\n\n```\n$ osdb help\nSearch and download subtitles from the command-line.\n\nUsage:\n  osdb\n  osdb [command]\n\nAvailable Commands:\n  get         Get subtitles for a file\n  hash        Shows OSDB hash for file.\n  help        Help about any command\n  imdb        Search IMDB\n  put         Upload subtitles for a file\n  version     Print the version number of osdb\n\nUse \"osdb [command] --help\" for more information about a command.\n```\n\nHence, to download French subtitles for a sample file:\n\n```\n$ osdb get -l fra sample.avi\n- Getting fra subtitles for file: sample.avi\n- No subtitles found!\n- Getting eng subtitles for file: sample.avi\n- Downloading to: sample.srt\n```\n\n\n# Hack...\n\nThe generated documentation for this package is available at:\nhttp://godoc.org/github.com/oz/osdb\n\nTo get started...\n\n * Install with `go get -d github.com/oz/osdb`,\n * and import `\"github.com/oz/osdb\"` in your Go code,\n * or try some of the examples in the README.\n\nTo access the OpenSubtitles' XML-RPC server you first need to allocate a\nclient, and then use it to login (even anonymously) in order to receive a\nsession token. With that, you are finally be allowed to talk. Here is a short\nexample:\n\n```go\npackage main\n\nimport \"github.com/oz/osdb\"\n\nfunc main() {\n\tc, err := osdb.NewClient()\n\tif err != nil {\n\t\t// ...\n\t}\n\n\t// Anonymous login will set c.Token when successful\n\tif err = c.LogIn(\"\", \"\", \"\"); err != nil {\n\t\t// ...\n\t}\n\n\t// etc.\n}\n\n```\n\n# Basic examples\n\n## Getting a user session token\n\nAlthough this library tries to be simple, to use OpenSubtitles' API you need to\nlogin first so as to receive a session token: without it you will not be able\nto call any API method.\n\n```go\nc, err := osdb.NewClient()\nif err != nil {\n\t// ...\n}\n\nif err = c.LogIn(\"user\", \"password\", \"language\"); err != nil {\n\t// ...\n}\n// c.Token is now set, and subsequent API calls will not be refused.\n```\n\nHowever, you do not need to register a user. To login anonymously, just leave\nthe `user` and `password` parameters blank:\n\n```go\nc.LogIn(\"\", \"\", \"\")\n```\n\n## Searching subtitles\n\nSubtitle search can be done in a number of ways: using special file-hashes,\nIMDB movie IDs, or even using full-text queries. Hash-based search will\ngenerally yield the best results, so this is what is demoed next. However, in\norder to search with this method, you *must* have a movie file to hash.\n\n```go\npath := \"/path/to/movie.avi\"\nlanguages := []string{\"eng\"}\n\n// Hash movie file, and search...\nres, err := client.FileSearch(path, languages)\nif err != nil {\n\t// ...\n}\n\nfor _, sub := range res {\n\tfmt.Printf(\"Found %s subtitles file \\\"%s\\\" at %s\\n\",\n\t\tsub.LanguageName, sub.SubFileName, sub.ZipDownloadLink)\n}\n```\n\n## Downloading subtitles\n\nLet's say you have just made a search, for example using `FileSearch()`, and as\nthe API provided a few results, you decide to pick one for download:\n\n```go\nsubs, err := c.FileSearch(...)\n\n// Download subtitle file, and write to disk using subs[0].SubFileName\nif err := c.Download(\u0026subs[0]); err != nil {\n\t// ...\n}\n\n// Alternatively, use the filename of your choice:\nif err := c.DownloadTo(\u0026subs[0], \"safer-name.srt\"); err != nil {\n\t// ...\n}\n```\n\n## Checking if a subtitle exists\n\nBefore trying to upload an allegedly \"new\" subtitles file to OSDB, you should\nalways check whether they already have it.\n\nAs some movies fit on more than one \"CD\" (remember those?), you will need to\nuse the `Subtitles` type (note the *s*?), one per subtitle file:\n\n```go\nsubs := osdb.Subtitles{\n\t\t{\n\t\t\tSubHash:       subHash,       // md5 hash of subtitle file\n\t\t\tSubFileName:   subFileName,\n\t\t\tMovieHash:     movieHash,     // see osdb.Hash()\n\t\t\tMovieByteSize: movieByteSize, // careful, it's a string...\n\t\t\tMovieFileName: movieFileName,\n\t\t},\n}\n```\n\nThen simply feed that to `HasSubtitles`, and you will be done.\n\n```go\nfound, err := c.HasSubtitles(subs)\nif err != nil {\n\t// ...\n}\n```\n\n## Hashing a file\n\nOSDB uses a custom checksum-hash to identify movie files. If you ever need\nthese:\n\n```go\nhash, err := osdb.Hash(\"somefile.avi\")\nif err != nil {\n\t// ...\n}\nfmt.Println(\"hash: %x\\n\", hash)\n```\n\n\n# On user agents...\n\nIf you have read OSDB's [developer documentation][osdb], you should notice that\nyou need to register an \"official\" user agent in order to use their API.\n\nBy default this library will present itself with the \"osdb-go\" agent, which is\nfine for me. However, if you need to change this, simply set the client's\n`UserAgent` with:\n\n```go\nc, err := osdb.NewClient()\nif err != nil {\n\t// ...\n}\nc.UserAgent = \"My custom user agent\"\n```\n\n# TODO\n\n - [ ] Move docs from README to godoc.org\n - [ ] [Full API coverage][apidocs]:\n  - [x] LogIn\n  - [x] LogOut\n  - [x] NoOperation\n  - [x] SearchSubtitles by hash\n  - [x] SearchSubtitles by IMDB IDs\n  - [ ] SearchToMail\n  - [x] DownloadSubtitles\n  - [x] TryUploadSubtitles\n  - [ ] UploadSubtitles\n  - [x] SearchMoviesOnIMDB\n  - [x] GetIMDBMovieDetails\n  - [ ] InsertMovie\n  - [ ] ServerInfo\n  - [ ] ReportWrongMovieHash\n  - [ ] SubtitlesVote\n  - [ ] AddComment\n  - [ ] GetSubLanguages\n  - [ ] DetectLanguage\n  - [ ] GetAvailableTranslations\n  - [ ] GetTranslation\n  - [ ] AutoUpdate\n  - [ ] CheckMovieHash\n  - [ ] CheckSubHash\n\n\n# License\n\nBSD, see the LICENSE file.\n\n[osdb]: http://trac.opensubtitles.org/projects/opensubtitles\n[apidocs]: http://trac.opensubtitles.org/projects/opensubtitles/wiki/XmlRpcIntro#XML-RPCmethods\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foz%2Fosdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foz%2Fosdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foz%2Fosdb/lists"}