botr (BitsOnTheRun)

Gem Version Dependency Status Code Climate


  • Ruby 2.0.0 or above
  • Some videos
  • An internet connection


gem install botr


A ruby API kit that manages the authentication, serialization and sending of API
calls to the Bits on the Run online video platform.


The botr gem includes support for the following Bits on the Run API classes:

  • videos
  • channels (video playlists)
  • players (based on JW Player)

Command-line Usage

$ gem install botr
$ botr upload /path/to/video.mp4 -k <API_KEY> -s <API_SECRET>

See botr help or botr help upload for more information.


require 'botr'


BOTR.configure do |config|
  config.api_key = "<botr_api_key>"
  config.secret_key = "<botr_secret_key>"

# NOTE: It is recommended to set the api key and the secret key as environment  
# variables and reference them using the `ENV` hash (e.g. config.api_key = ENV["BOTR_API_KEY"]).


# create a new video metadata container
vid =
vid.create(title: "My cat video", author: "Me")

# upload actual video file

# update the properties of a video
vid.update(title: "My super awesome cat video", description: "Mr. Snicker  
apparently doesn't like being filmed.")

# delete a given video and all its conversions

# list all videos
BOTR::Video.all # => [#<BOTR::Video>, #<BOTR::Video>, ...]

# list only certain videos
BOTR::Video.list(search: "cat", order_by: "date")

# find a certain video by video key
cat_vid ="<video_key>") # => #<BOTR::Video @key="[video_key]">

Video Conversions

# create a new video conversion
480p_vid =
480p_vid.create("<video_key>", "<template_key>")

# delete a given video conversion from the CDN

# list all video conversions for a given video
BOTR::VideoConversion.list("<video_key>", result_limit: 5)

# find a given video conversion by its conversion key
aac_vid ="<conversion_key>")

Video Thumbnails

# find a video thumbnail
thumb ="<video_key>")

# update a video's thumbnail
thumb.update(position: 7.25) # updates the video's thumbnail to the image at  
7.25 seconds

# upload a new video thumbnail

Video Captions

# create a new video caption
espanol =
espanol.create(label: "esp")

# upload the actual caption file

# update the video caption
espanol.update(label: "Spanish")

# delete a video caption

# list the captions for a video
BOTR::VideoCaption.list("<video_key>", order_by: "label:asc")

# get the caption information for a video
cap ="<video_key>")

Video Tags

# list a video's tags

# search for video tags matching a certain criteria
BOTR::VideoTag.list(search: "kitty")

Video Views

date =, 10, 31)
unix_timestamp = date.to_i

# list view statistics by video
BOTR::VideoView.list(start_date: unix_timestamp)

# list view statistics by day
BOTR::VideoView.list(list_by: "day", group_days: false)

# list view statistics, grouping by day
BOTR::VideoView.list(list_by: "day", group_days: true)

# list view statistics in aggregate
BOTR::VideoView.list(list_by: "day", aggregate: true)

# find a video's statistics"<video_key>")

Video Engagements

# display engagement analytics for a single video"<video_key>")

Channels (Playlists)

# create a manual playlist
my_picks =
my_picks.create(title: "My Picks", type: "manual")

# create a dynamic playlist
top_picks =
top_picks.create(title: "Trending", type: "automatic")

# add videos to a dynamic playlist
top_picks.update(description: "Top 10 videos", tags: "kitty",  
sort_order: "views-desc", videos_max: 10)

# delete a channel

# get a list of all channels

# get a list of all dynamic "picks" channels
BOTR::Channel.list(types_filter: "dynamic", search: "top")

# get a specific channel
my_ch ="<channel_key>")

Channel Videos

# get a list of videos in a channel

# get video info. from a channel
second_vid =, position: 2)

# remove a video from a manual channel

# add a video to a manual channel
snicker_falls ={key: "<video_key>"})

# move a video to a different position in a manual channel
BOTR::ChannelVideo.update(my_picks.key, position_from: 10, position_to: 2)

Channel Thumbnails

# update a channel's thumbnail
new_tumb ={key: "<channel_key>"})

# get the status of a video thumbnail creation (it takes about 10 seconds  
    before a new thumbnail is ready to show)
thumb_stat ="<channel_key>")
thumb_stat.status # => "ready"

Channel Views

# get view stats by channel
BOTR::ChannelView.list(list_by: "channel")

# get channel view stats by day
BOTR::ChannelView.list(list_by: "day", group_days: false)

# get channel view stats by grouped days (i.e. in months and years)
BOTR::ChannelView.list(list_by: "day", group_days: true)

# get aggregate channel view stats
BOTR::ChannelView.list(aggregate: true)

# get view stats for a specific channel
ch_stats ="<channel_key>", group_days: false)

# get view stats for a specific channel in months and years
ch_group_stats ="<channel_key>", group_days: true)

# get aggregate view stats for a specific channel
ch_report ="<channel_key>", aggregate: true)


# create a JW Player
new_player =
new_player.create("Awesome Player", "<sharing_player_key>", autostart: false)

# update a player's settings
new_player.update(controlbar: bottom, repeat: always)

# delete a player

# get a list of all players

# list only certain players
BOTR::Player.list(search: "awesome")

# get a specific player
my_player ="<player_key>")

Player Views

# get views by player
BOTR::PlayerView.list(list_by: "player")

# get views by day
BOTR::PlayerView.list(list_by: "day", group_days: flase, include_empty_days: true)

# get views by month and year
BOTR::PlayerView.list(list_by: "day", group_days: true)

# get aggregate player view
BOTR::PlayerView.list(aggregate: true)

# get view stats for a specific player
player_stats ="<player_key>", group_days: false)

# get view stats for a specific player in months and years
player_group_stats ="<player_key>", group_days: true)

# get aggregate view stats for a specific player
player_report ="<player_key>", aggregate: true)


  • Add support for accounts
  • Add support for resumable file uploads
  • Add support for content signing
  • Enhance support for custom params
  • Elegantly handle errors

Additional Resources

For more information, see:


Copyright (c) 2013 Bertrand Karerangabo

See LICENSE for details.