Repository files navigation

A Go client forOpenSubtitles.

This project allows you to search and download subtitles from OpenSubtitles. Itcomes both as a command-line program, and a library that you can use from otherprograms.

If you need to search or download subtitles, then you should find what you needfrom the latest releases, otherwise theTODOsection highlights what remains to be done regarding API coverage.

If you want to compile the CLI interface for OpenSubtitles, then install thelatestGo release, and run:

go get github.com/oz/osdb && go install github.com/oz/osdb/cmd/osdb

Provided that you setup your Go environment correctly, you now have a basicosdb command to interact with OpenSubtitles' API.

$ osdb helpSearch and download subtitles from the command-line.Usage:  osdb  osdb [command]Available Commands:  get         Get subtitles for a file  hash        Shows OSDB hash for file.  help        Help about any command  imdb        Search IMDB  put         Upload subtitles for a file  version     Print the version number of osdbUse "osdb [command] --help" for more information about a command.

Hence, to download French subtitles for a sample file:

$ osdb get -l fra sample.avi- Getting fra subtitles for file: sample.avi- No subtitles found!- Getting eng subtitles for file: sample.avi- Downloading to: sample.srt

The generated documentation for this package is available at:http://godoc.org/github.com/oz/osdb

To get started...

• Install withgo get -d github.com/oz/osdb,
• and import"github.com/oz/osdb" in your Go code,
• or try some of the examples in the README.

To access the OpenSubtitles' XML-RPC server you first need to allocate aclient, and then use it to login (even anonymously) in order to receive asession token. With that, you are finally be allowed to talk. Here is a shortexample:

package mainimport"github.com/oz/osdb"funcmain() {c,err:=osdb.NewClient()iferr!=nil {// ...}// Anonymous login will set c.Token when successfuliferr=c.LogIn("","","");err!=nil {// ...}// etc.}

Although this library tries to be simple, to use OpenSubtitles' API you need tologin first so as to receive a session token: without it you will not be ableto call any API method.

c,err:=osdb.NewClient()iferr!=nil {// ...}iferr=c.LogIn("user","password","language");err!=nil {// ...}// c.Token is now set, and subsequent API calls will not be refused.

However, you do not need to register a user. To login anonymously, just leavetheuser andpassword parameters blank:

c.LogIn("","","")

Subtitle search can be done in a number of ways: using special file-hashes,IMDB movie IDs, or even using full-text queries. Hash-based search willgenerally yield the best results, so this is what is demoed next. However, inorder to search with this method, youmust have a movie file to hash.

path:="/path/to/movie.avi"languages:= []string{"eng"}// Hash movie file, and search...res,err:=client.FileSearch(path,languages)iferr!=nil {// ...}for_,sub:=rangeres {fmt.Printf("Found %s subtitles file\"%s\" at %s\n",sub.LanguageName,sub.SubFileName,sub.ZipDownloadLink)}

Let's say you have just made a search, for example usingFileSearch(), and asthe API provided a few results, you decide to pick one for download:

subs,err:= c.FileSearch(...)// Download subtitle file, and write to disk using subs[0].SubFileNameiferr:=c.Download(&subs[0]);err!=nil {// ...}// Alternatively, use the filename of your choice:iferr:=c.DownloadTo(&subs[0],"safer-name.srt");err!=nil {// ...}

Before trying to upload an allegedly "new" subtitles file to OSDB, you shouldalways check whether they already have it.

As some movies fit on more than one "CD" (remember those?), you will need touse theSubtitles type (note thes?), one per subtitle file:

subs:= osdb.Subtitles{{SubHash:subHash,// md5 hash of subtitle fileSubFileName:subFileName,MovieHash:movieHash,// see osdb.Hash()MovieByteSize:movieByteSize,// careful, it's a string...MovieFileName:movieFileName,},}

Then simply feed that toHasSubtitles, and you will be done.

found,err:=c.HasSubtitles(subs)iferr!=nil {// ...}

OSDB uses a custom checksum-hash to identify movie files. If you ever needthese:

hash,err:=osdb.Hash("somefile.avi")iferr!=nil {// ...}fmt.Println("hash: %x\n",hash)

If you have read OSDB'sdeveloper documentation, you should notice thatyou need to register an "official" user agent in order to use their API.

By default this library will present itself with the "osdb-go" agent, which isfine for me. However, if you need to change this, simply set the client'sUserAgent with:

c,err:=osdb.NewClient()iferr!=nil {// ...}c.UserAgent="My custom user agent"

• Move docs from README to godoc.org
• Full API coverage:
• LogIn
• LogOut
• NoOperation
• SearchSubtitles by hash
• SearchSubtitles by IMDB IDs
• SearchToMail
• DownloadSubtitles
• TryUploadSubtitles
• UploadSubtitles
• SearchMoviesOnIMDB
• GetIMDBMovieDetails
• InsertMovie
• ServerInfo
• ReportWrongMovieHash
• SubtitlesVote
• AddComment
• GetSubLanguages
• DetectLanguage
• GetAvailableTranslations
• GetTranslation
• AutoUpdate
• CheckMovieHash
• CheckSubHash

BSD, see the LICENSE file.