everybit

This gem encapsulates the functionality needed to access the Everybit Streaming Media API.

Installation

Add this line to your application's Gemfile:

gem 'everybit'

And then execute:

$ bundle

Or install it yourself with the usual gem install command:

$ gem install everybit

Requirements

• Ruby 1.9.3
• rest-client, multi_json

Usage

Detailed documentation for communicating with the Everybit Streaming Media API is available here. The information in this readme is only a brief introduction. If you have a specific problem with this gem you can open an issue or, for more specific help with using the API in general, you can visit our dedicated support site.

Preparation

All communication with the Everybit Streaming Media API must be accompanied by your Everybit API key. This key is available in the My Account section of our Dashboard Media Management Portal and is randomly generated upon successful registration.

To setup the everybit gem with your API key, simply set it in the global Everybit object:

Everybit.api_key = '1a2b3c4d5e6f7g8h9i'

You can also view and change the base URL to which the gem will submit your media's details:

Everybit.api_base
# => 'https://api.everybit.co'

Everybit.api_base = 'https://api.example.com'
# => 'https://api.example.com'

Accounts

The library allows you to retrieve the details for the account attached to the API key provided:

Everybit.api_key = 'YOUR_API_KEY'
acct = Everybit::Account.retrieve

acct.code
# => 200

acct.status # this is the status of the request, not the account itself
# => true

acct[:uuid]       # => '787c8956-1857-4771-9d4e-b99b4dedfeae'
acct[:email]      # => '[e-mail]'
acct[:username]   # => 'jsmith'
acct[:first_name] # => 'John'
acct[:last_name]  # => 'Smith'

Videos

Status

To check the status of a video that's been uploaded for encoding and conversion:

Everybit.api_key = 'YOUR_API_KEY'
video = Everybit::Video.status('UUID_OF_VIDEO')

video.code
# => 200

video.status # this is the status of the request, not the video itself
# => true

video[:uuid]           # => 'UUID_OF_VIDEO'
video[:processing]     # => true|false
video[:progress]       # => 0-100
video[:completed]      # => true|false
video[:completed_date] # => date|nil

Details

To request the details of a video that's completed encoding and conversion:

Everybit.api_key = 'YOUR_API_KEY'
video = Everybit::Video.details('UUID_OF_VIDEO')

video.code
# => 200

video.status # this is the status of the request, not the video itself
# => true

video[:created_date]      # => 1362636380 (milliseconds since epoch)
video[:external_callback] # => the callback url provided during create request
video[:lat]               # => 40.714353
video[:lon]               # => -74.005973
video[:owner_uuid]        # => uuid of the user that created the video
video[:source_url]        # => the source url provided during create request
video[:summary]           # => 'A short description about the video.'
video[:title]             # => 'Video Title'
video[:play_count]        # => number of times this video has been played
video[:data_consumed]     # => amount of data streamed for this video
video[:tags]              # => [array of tags]
video[:visibility]        # => 'public|protected|private'
video[:last_updated]      # => 1362636380 (milliseconds since epoch)
video[:uuid]              # => UUID_OF_VIDEO
video[:thumbnail]         # => path to a thumbnail of the video's full size hold frame image
video[:original_file]     # => path to original file uploaded during create request
video[:player_url]        # => url to the video's player
video[:media_info]        # => {HASH OF DETAILED MEDIA INFO}
video[:player_attributes] # => {HASH OF CUSTOMIZABLE PLAYER ATTRIBUTES}
video[:versions]          # => {HASH OF EACH VERSION CREATED DURING ENCODING}

Create

When you need to upload a new video for encoding and conversion, use the create method. Besides your api key, there are eight additional pieces of information that can be sent in a create request:

• title (required)
• summary
• tags
• lat
• lon
• visibility (required)
• source_file (required)
• callback_url (required)

Everybit.api_key = 'YOUR_API_KEY'

video_details = {
  title: 'Dolphin Training',
  summary: 'How to train your dolphin like a pro.',
  tags: ['dolphin', 'training'],
  lat: 40.714353,
  lon: -74.005973,
  visibility: 'public',
  source_file: 'http://example.com/dolphin.mp4',
  callback_url: 'http://example.com/everybit_callback'
}

video = Everybit::Video.create(video_details)

The request will return one of two responses. A success response if the video has successfully started encoding and conversion, or an error response if something prevented the video from being created:

Success response:
{
  "code": 200,
  "status": true,
  "data": {
    "uuid": UUID
  }
}

Error response:
{
  "code": 400,
  "status": false,
  "data": {
    "error" "specific error message here"
  }
}

Update

When you need to change the attributes for a video that's completed encoding, use the update method.

Everybit.api_key = 'YOUR_API_KEY'

video_updates = {
  lat: 39.737567,
  lon: -104.984718,
  summary: 'updated summary',
  title: 'updated title',
  tags: ['updated', 'tags'],
  visibility: 'public|protected|private',
  player_attributes: {
    volume_slider_color: '#ffffff',
    time_color: '#ffffff',
    buffer_background_color: '#f9f9f9',
    progress_background_color: '#bb0000',
    show_play_button: true,
    auto_hide_controls: true,
    auto_play: false,
    show_embed_code: true,
    template_name: 'default',
    streaming_type: 'progressive|streaming'
  }
}

video = Everybit::Video.update(video_updates)

The response from an update request is the same as a details response, except it will contain your updated details.

Delete

To delete a video that's completed encoding and conversion:

Everybit.api_key = 'YOUR_API_KEY'
video = Everybit::Video.delete('UUID_OF_VIDEO')

The request will return one of two responses. A success response if the video was successfully deleted, or an error response if something prevented the video from being deleted:

Success response:
{
  "code": 200,
  "status": true,
  "data": {
    "message": "your video was deleted successfully"
  }
}

Error response:
{
  "code": 400,
  "status": false,
  "data": {
    "error": "specific error message here"
  }
}

Tests

All tests are located in the spec directory and are written using Minitest's spec (expectation) syntax. They've been divided into test files according to the resource under test. So, for example, all the tests for the Account class can be found in spec/account_spec.rb. You can run all tests with the usual rake command with no arguments. If you'd like to run only one set of tests, you can specify them using the minitest namespace for that resource. e.g. rake minitest:account.

A list of available rake tasks can be output with the usual rake -T command.

Contributing

• Fork it
• Create your feature branch git checkout -b my-new-feature
• Commit your changes git commit -am 'Add some feature'
• Push to the branch git push origin my-new-feature
• Create new Pull Request

If you're developing locally, the gem's Rakefile includes Bundler's gem tasks. So calling rake build will build the gem and rake install will first build and then install the gem locally. A gem binary called everybit-console has been included to make local testing a little easier. It will launch an irb session with the everybit gem already required.