Awesome Open Source
Awesome Open Source
Transmissionrpc
Golang bindings for Transmission RPC API
Stars
35
License
mit
Open Issues
1
Most Recent Commit
8 months ago
Related Projects
go (14,452)
golang (3,681)
golang-library (135)
transmission (38)
torrents (16)
Repo

TransmissionRPC

go.dev reference Go report card

Golang bindings to Transmission (bittorrent) RPC interface.

Even if there is some high level wrappers/helpers, the goal of this lib is to stay close to the original API in terms of methods and payloads while enhancing certain types to be more "golangish": timestamps are converted from/to time.Time, numeric durations in time.Duration, booleans in numeric form are converted to real bool, etc...

Also payload generation aims to be precise: when several values can be added to a payload, only instanciated values will be forwarded (and kept !) to the final payload. This means that the default JSON marshalling (with omitempty) can't always be used and therefor a manual, reflect based, approach is used to build the final payload and accurately send what the user have instanciated, even if a value is at its default type value.

This lib follows the transmission v15 RPC specification.

Getting started

First the main client object must be instantiated with New(). In its basic form only host/ip, username and password must be provided. Default will apply for port (9091) rpc URI (/transmission/rpc) and others values.

transmissionbt := transmissionrpc.New("127.0.0.1", "rpcuser", "rpcpass", nil)

But advanced values can also be configured to your liking using AdvancedConfig. Each value of AdvancedConfig with a type default value will be replaced by the lib default value, so you can set only the ones you want:

transmissionbt := transmissionrpc.New("bt.mydomain.net", "rpcuser", "rpcpass",
    &transmissionrpc.AdvancedConfig{
        HTTPS: true,
        Port:  443,
    })

The remote RPC version can be checked against this library before starting to operate:

ok, serverVersion, serverMinimumVersion, err := transmission.RPCVersion()
if err != nil {
    panic(err)
}
if !ok {
    panic(fmt.Sprintf("Remote transmission RPC version (v%d) is incompatible with the transmission library (v%d): remote needs at least v%d",
        serverVersion, transmissionrpc.RPCVersion, serverMinimumVersion))
}
fmt.Printf("Remote transmission RPC version (v%d) is compatible with our transmissionrpc library (v%d)\n",
    serverVersion, transmissionrpc.RPCVersion)

Features

Torrent Requests

Torrent Action Requests

Each rpc methods here can work with ID list, hash list or recently-active magic word. Therefor, there is 3 golang method variants for each of them.

transmissionbt.TorrentXXXXIDs(...)
transmissionbt.TorrentXXXXHashes(...)
transmissionbt.TorrentXXXXRecentlyActive()
  • torrent-start

Check TorrentStartIDs(), TorrentStartHashes() and TorrentStartRecentlyActive().

Ex:

err := transmissionbt.TorrentStartIDs([]int64{55})
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    fmt.Println("yay")
}
  • torrent-start-now

Check TorrentStartNowIDs(), TorrentStartNowHashes() and TorrentStartNowRecentlyActive().

Ex:

err := transmissionbt.TorrentStartNowHashes([]string{"f07e0b0584745b7bcb35e98097488d34e68623d0"})
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    fmt.Println("yay")
}
  • torrent-stop

Check TorrentStopIDs(), TorrentStopHashes() and TorrentStopRecentlyActive().

Ex:

err := transmissionbt.TorrentStopIDs([]int64{55})
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    fmt.Println("yay")
}
  • torrent-verify

Check TorrentVerifyIDs(), TorrentVerifyHashes() and TorrentVerifyRecentlyActive().

Ex:

err := transmissionbt.TorrentVerifyHashes([]string{"f07e0b0584745b7bcb35e98097488d34e68623d0"})
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    fmt.Println("yay")
}
  • torrent-reannounce

Check TorrentReannounceIDs(), TorrentReannounceHashes() and TorrentReannounceRecentlyActive().

Ex:

err := transmissionbt.TorrentReannounceRecentlyActive()
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    fmt.Println("yay")
}

Torrent Mutators

  • torrent-set

Mapped as TorrentSet().

Ex: apply a 1 MB/s limit to a torrent.

uploadLimited := true
uploadLimitKBps := int64(1000)
err := transmissionbt.TorrentSet(&transmissionrpc.TorrentSetPayload{
    IDs:           []int64{55},
    UploadLimited: &uploadLimited,
    UploadLimit:   &uploadLimitKBps,
})
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    fmt.Println("yay")
}

There is a lot more mutators available.

Torrent Accessors

  • torrent-get

All fields for all torrents with TorrentGetAll():

torrents, err := transmissionbt.TorrentGetAll()
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    fmt.Println(torrents) // meh it's full of pointers
}

All fields for a restricted list of ids with TorrentGetAllFor():

torrents, err := transmissionbt.TorrentGetAllFor([]int64{31})
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    fmt.Println(torrents) // meh it's still full of pointers
}

Some fields for some torrents with the low level accessor TorrentGet():

torrents, err := transmissionbt.TorrentGet([]string{"status"}, []int64{54, 55})
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    for _, torrent := range torrents {
        fmt.Println(torrent.Status) // the only instanciated field, as requested
    }
}

Some fields for all torrents, still with the low level accessor TorrentGet():

torrents, err := transmissionbt.TorrentGet([]string{"id", "name", "hashString"}, nil)
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    for _, torrent := range torrents {
        fmt.Println(torrent.ID)
        fmt.Println(torrent.Name)
        fmt.Println(torrent.HashString)
    }
}

Valid fields name can be found as JSON tag on the Torrent struct.

Adding a Torrent

  • torrent-add

Adding a torrent from a file (using TorrentAddFile wrapper):

filepath := "/home/hekmon/Downloads/ubuntu-17.10.1-desktop-amd64.iso.torrent"
torrent, err := transmissionbt.TorrentAddFile(filepath)
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    // Only 3 fields will be returned/set in the Torrent struct
    fmt.Println(*torrent.ID)
    fmt.Println(*torrent.Name)
    fmt.Println(*torrent.HashString)
}

Adding a torrent from a file (using TorrentAddFileDownloadDir wrapper) to a specified DownloadDir (this allows for separation of downloads to target folders):

filepath := "/home/hekmon/Downloads/ubuntu-17.10.1-desktop-amd64.iso.torrent"
torrent, err := transmissionbt.TorrentAddFileDownloadDir(filepath, "/path/to/other/download/dir")
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    // Only 3 fields will be returned/set in the Torrent struct
    fmt.Println(*torrent.ID)
    fmt.Println(*torrent.Name)
    fmt.Println(*torrent.HashString)
}

Adding a torrent from an URL (ex: a magnet) with the real TorrentAdd method:

magnet := "magnet:?xt=urn:btih:f07e0b0584745b7bcb35e98097488d34e68623d0&dn=ubuntu-17.10.1-desktop-amd64.iso&tr=http%3A%2F%2Ftorrent.ubuntu.com%3A6969%2Fannounce&tr=http%3A%2F%2Fipv6.torrent.ubuntu.com%3A6969%2Fannounce"
torrent, err := btserv.TorrentAdd(&transmissionrpc.TorrentAddPayload{
    Filename: &magnet,
})
if err != nil {
    fmt.Fprintln(os.Stderr, err)
} else {
    // Only 3 fields will be returned/set in the Torrent struct
    fmt.Println(*torrent.ID)
    fmt.Println(*torrent.Name)
    fmt.Println(*torrent.HashString)
}

Which would output:

55
ubuntu-17.10.1-desktop-amd64.iso
f07e0b0584745b7bcb35e98097488d34e68623d0

Adding a torrent from a file, starting it paused:

filepath := "/home/hekmon/Downloads/ubuntu-17.10.1-desktop-amd64.iso.torrent"
b64, err := transmissionrpc.File2Base64(filepath)
if err != nil {
	fmt.Fprintf(os.Stderr, "can't encode '%s' content as base64: %v", filepath, err)
} else {
	// Prepare and send payload
	paused := true
	torrent, err := transmissionbt.TorrentAdd(&transmissionrpc.TorrentAddPayload{MetaInfo: &b64, Paused: &paused})
}

Removing a Torrent

  • torrent-remove

Mapped as TorrentRemove().

Moving a Torrent

  • torrent-set-location

Mapped as TorrentSetLocation().

Renaming a Torrent path

  • torrent-rename-path

Mapped as TorrentRenamePath().

Session Requests

Session Arguments

  • session-set

Mapped as SessionArgumentsSet().

  • session-get

Mapped as SessionArgumentsGet().

Session Statistics

  • session-stats

Mapped as SessionStats().

Blocklist

  • blocklist-update

Mapped as BlocklistUpdate().

Port Checking

  • port-test

Mapped as PortTest().

Ex:

    st, err := transmissionbt.PortTest()
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
    }
    if st {
        fmt.Println("Open!")
    }

Session Shutdown

  • session-close

Mapped as SessionClose().

Queue Movement Requests

  • queue-move-top

Mapped as QueueMoveTop().

  • queue-move-up

Mapped as QueueMoveUp().

  • queue-move-down

Mapped as QueueMoveDown().

  • queue-move-bottom

Mapped as QueueMoveBottom().

Free Space

  • free-space

Mappped as FreeSpace().

Ex: Get the space available for /data.

    freeSpace, err := transmissionbt.FreeSpace("/data")
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
    } else  {
        fmt.Printd("%s | %d | %v", freeSpace, freeSpace, freeSpace)
    }
}

For more information about the freeSpace type, check the ComputerUnits library.


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
go (14,452) 
golang (3,681) 
golang-library (135) 
transmission (38) 
torrents (16) 

Find Open Source By Browsing 7,000 Topics Across 59 Categories

Advertising 📦 10
All Projects
Application Programming Interfaces 📦 124
Applications 📦 192
Artificial Intelligence 📦 78
Blockchain 📦 73
Build Tools 📦 113
Cloud Computing 📦 80
Code Quality 📦 28
Collaboration 📦 32
Command Line Interface 📦 49
Community 📦 83
Companies 📦 60
Compilers 📦 63
Computer Science 📦 80
Configuration Management 📦 42
Content Management 📦 175
Control Flow 📦 213
Data Formats 📦 78
Data Processing 📦 276
Data Storage 📦 135
Economics 📦 64
Frameworks 📦 215
Games 📦 129
Graphics 📦 110
Hardware 📦 152
Integrated Development Environments 📦 49
Learning Resources 📦 166
Legal 📦 29
Libraries 📦 129
Lists Of Projects 📦 22
Machine Learning 📦 347
Mapping 📦 64
Marketing 📦 15
Mathematics 📦 55
Media 📦 239
Messaging 📦 98
Networking 📦 315
Operating Systems 📦 89
Operations 📦 121
Package Managers 📦 55
Programming Languages 📦 245
Runtime Environments 📦 100
Science 📦 42
Security 📦 396
Social Media 📦 27
Software Architecture 📦 72
Software Development 📦 72
Software Performance 📦 58
Software Quality 📦 133
Text Editors 📦 49
Text Processing 📦 136
User Interface 📦 330
User Interface Components 📦 514
Version Control 📦 30
Virtualization 📦 71
Web Browsers 📦 42
Web Servers 📦 26
Web User Interface 📦 210
"Transmissionrpc" and other potentially trademarked words, copyrighted images and copyrighted readme contents likely belong to the legal entity who owns the "Hekmon" organization. Awesome Open Source is not affiliated with the legal entity who owns the "Hekmon" organization.