This project provides a starting point for integrating the Brightcove Media API into your application. It provides simple ways to interact with the API.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


WARNING: The Media API is deprecated and should not be used for new projects. More information.

Ruby gem for interacting with the Brightcove media API.


  • HTTParty

  • JSON (for post_file(...) and post_file_streaming(...) methods)

  • rest-client (for the post_file(...) method)
  • multipart-post (for the post_file_streaming(...) method)
  • orderedhash (only if you're using Ruby 1.8.7)


gem install brightcove-api


require 'brightcove-api'
=> true

brightcove ='0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.')
=> #<Brightcove::API:0x114dbc8 @token="0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.", @api_url="">

response = brightcove.get('find_all_videos', {:page_size => 3, :video_fields => 'id,name,linkURL,linkText'})
=> {"items"=>[{"name"=>"Documentarian Skydiving", "id"=>496518762, "linkText"=>nil, "linkURL"=>nil}, {"name"=>"Surface Tricks", "id"=>496518763, "linkText"=>nil, "linkURL"=>nil}, {"name"=>"Free Skiing", "id"=>496518765, "linkText"=>nil, "linkURL"=>nil}], "page_number"=>0, "page_size"=>3, "total_count"=>-1}

response = brightcove.get('find_all_videos', {:page_size => 5, :sort_by => 'PLAYS_TOTAL'})
=> {"items"=>[{"longDescription"=>nil, "name"=>"Wild Slopes '06", "lastModifiedDate"=>"1171324523307", "thumbnailURL"=>"", "tags"=>["adventure", "snowboarding"], "playsTrailingWeek"=>35, "shortDescription"=>"A ski and snowboard movie that challenges the hype and dares you to see what freeskiing and snowboarding have become. Documenting the very best of this year's riding and culture.", "playsTotal"=>4458, "adKeys"=>nil, "id"=>496518766, "length"=>51251, "videoStillURL"=>"", "publishedDate"=>"1171324434811", "creationDate"=>"1171267200000", "linkText"=>nil, "economics"=>"FREE", "referenceId"=>"title010", "linkURL"=>nil}, {"longDescription"=>nil, "name"=>"Jellyfish", "lastModifiedDate"=>"1245181300374", "thumbnailURL"=>"", "tags"=>["sea", "custom skins"], "playsTrailingWeek"=>46, "shortDescription"=>"Jellyfish", "playsTotal"=>4081, "adKeys"=>nil, "id"=>26512561001, "length"=>28400, "videoStillURL"=>"", "publishedDate"=>"1245172164326", "creationDate"=>"1245172164326", "linkText"=>nil, "economics"=>"AD_SUPPORTED", "referenceId"=>nil, "linkURL"=>nil}, {"longDescription"=>"Long Description", "name"=>"Demo Title 2", "lastModifiedDate"=>"1263581295791", "thumbnailURL"=>"", "tags"=>[], "playsTrailingWeek"=>1, "shortDescription"=>"Short Description", "playsTotal"=>3876, "adKeys"=>nil, "id"=>276024035, "length"=>418742, "videoStillURL"=>"", "publishedDate"=>"1161296014264", "creationDate"=>"1161241200000", "linkText"=>"Related Link", "economics"=>"FREE", "referenceId"=>nil, "linkURL"=>""}, {"longDescription"=>nil, "name"=>"Dolphins", "lastModifiedDate"=>"1263581295790", "thumbnailURL"=>"", "tags"=>["sea", "custom skins"], "playsTrailingWeek"=>30, "shortDescription"=>"Dolphins", "playsTotal"=>3870, "adKeys"=>nil, "id"=>26511963001, "length"=>12800, "videoStillURL"=>"", "publishedDate"=>"1245171732987", "creationDate"=>"1245171732987", "linkText"=>nil, "economics"=>"AD_SUPPORTED", "referenceId"=>nil, "linkURL"=>nil}, {"longDescription"=>nil, "name"=>"Welcome to Brightcove 3", "lastModifiedDate"=>"1225134261511", "thumbnailURL"=>"", "tags"=>[], "playsTrailingWeek"=>0, "shortDescription"=>"Tareef Kawaf, Brightcove's SVP of Engineering, welcomes you to Brightcove 3.", "playsTotal"=>3349, "adKeys"=>nil, "id"=>1858922805, "length"=>53820, "videoStillURL"=>"", "publishedDate"=>"1225134261508", "creationDate"=>"1224096089173", "linkText"=>nil, "economics"=>"AD_SUPPORTED", "referenceId"=>nil, "linkURL"=>nil}], "page_number"=>0, "page_size"=>5, "total_count"=>-1}

response ='delete_video', {:video_id => '595153263001'})
=> {"result"=>{}, "id"=>nil, "error"=>nil}

If you want to perform a file upload, for example, to create a video, you can use the post_file() method.

response = brightcove.post_file('create_video', '/path/to/', :video => {:shortDescription => 'Short Description', :name => 'Video name'})
=> {"result"=>653155417001, "error=>nil, "id"=>nil}

If you want to perform a file upload using HTTP streaming, for example, to create a video, you can use the post_file_streaming() method.

response = brightcove.post_file_streaming('create_video', '/path/to/', 'video/quicktime', :video => {:shortDescription => 'Short Description', :name => 'Video name'})
=> {"result"=>653155417001, "error=>nil, "id"=>nil}

You can also use the post_io_streaming(api_method, file, content_type, parameters) method which takes an I/O handle instead of a filename.

You can now pass {:output => 'mrss'} in the get(...) method to return output in Media RSS format. Example:

response = brightcove.get('find_all_videos', {:output => 'mrss'})


To replicate one of the brightcove search API examples:

find all videos that have "football" and "Chicago" in the name, short description, or long description, and which also have the tag "free", and also have either the tag "color" or the tag "technicolor"

brightcove =
response = brightcove.get('search_videos', {
  :any => [ "tag:color", "tag:technicolor" ],
  :all => ["football", "chicago", "tag:free"]


The brightcove-api gem is built and tested under Ruby 2.2.1.

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.


Copyright (c) 2010-2015 David Czarnecki. See LICENSE for details.