[object Object] Icon

Encoding
Learn how to create, start, manage and modify Encodings

[object Object] Icon

Player
Learn how to create, start, manage and modify Players

[object Object] Icon

Analytics
Learn how to create, start, manage and modify Analyticss

Docs Home
User shortcuts for search
Focus by pressing f
Hide results by pressing Esc
Navigate via   keys

Ruby SDK

Encoding Overview

Starting an encoding triggers encoding VMs to be spun up, the input file will be downloaded and distributed in chunks between all of them. The VMs encode these chunks of all representations (muxings) in parallel and write the encoded segments to the output.
This approach makes Bitmovin's encoding the fastest in the world.

EncodingProcessNoinlineSvg

The following tutorials guides you through on how to create a simple encoding, while also explaining the resources that build up an encoding and manifest.

Step 1: Add the Bitmovin SDK to Your ProjectLink Icon

Add the Bitmovin SDK

Add this to your Gemfile:
For the latest version please refer to the GitHub repository.

And then execute:

Step 2: Setup a Bitmovin API Client InstanceLink Icon

Initialize a Bitmovin API Client

The Bitmovin API client instance is used for all communication with the Bitmovin REST API, pass your API key to authenticate with the API.

You can find the API key in the dashboard.

Step 3: Create an InputLink Icon

Create Input

An input holds the configuration to access a specific file storage, from which the encoder will download the source file.

We support various types of input sources including HTTP(S), (S)FTP, Google Cloud Storage (GCS), Amazon Simple Storage Service (S3), Azure Blob Storage, and all cloud storage vendors that offer an S3 compatible interface.

Below we are creating an input. You can change the input type on the top right of the code panel.

Reuse Inputs

Inputs refer to a location, not a specific file.
This makes them easily reusable. Create an input once and reuse it for all your encodings.

Hint: All resources in our API are identified by a unique id which enables you to reuse many resources. So you only have to create one input for each location and can reuse it for all encodings.

Step 4: Create an OutputLink Icon

Create Output

Outputs define where the manifests and encoded segments will be written to.
Like inputs, outputs represent a set of information needed to access a specific storage. From this storage players can access the content for playback.

Reuse Outputs

Similar to inputs, outputs also refer to a location, not a specific file.
So they're exactly as reusable as inputs. Create it once and reuse it for all your encodings.

Step 5: Create Codec ConfigurationsLink Icon

Codec Configurations

Codec configurations specify the codec and its parameters (eg. media codec, bitrate, frame rate, sampling rate).
They are used to encode the input stream coming from your input file.

Video Codec Configurations

Below we are creating video codec configurations. We support a multitude of codecs, including H264, H265, VP9, AV1 and many more.
For simplicity, we use H264 now, but you can easily change that after finishing the getting started.

Audio Codec Configurations

As audio codec configuration we are creating one AAC configuration.
We also support many more audio codecs including Opus, Vorbis, AC3, E-AC3 and MP2.

Reusing Codec Configurations

As inputs and outputs, codec configurations can also be reused.
To use existing video or audio codec configurations, loading them with their id.

Step 6: Create EncodingLink Icon

Create Encoding

An encoding is a collection of resources (inputs, outputs, codec configurations etc.), mapped to each other.

The cloud region defines in which cloud and region your encoding will be started.
If you don't set it, our encoder takes the region closest to your input and output.

Inputs, outputs and codec configurations can be reused among many encodings. Other resources are specific to one encoding, like streams, which we'll create below.

Streams

A stream maps an audio or video input stream of your input file (called input stream) to one audio or video codec configuration.
The following example uses the selection mode AUTO, which will select the first available video input stream of your input file.
You can choose an input file from 3 predefined examples on the top right of the code panel.

Video Stream

Audio Stream

Step 7: Create a MuxingLink Icon

Muxings

A muxing defines which container format will be used for the encoded video or audio files (segmented TS, progressive TS, MP4, FMP4, ...). It requires a stream, an output, and the output path, where the generated segments will be written to.

FMP4 muxings are used for DASH manifest representations, TS muxings for HLS playlist representations.

FMP4

Video Muxings

Audio Muxings

Hint: To optimize your content for a specific use-case you can also provide a custom segment length. Further, you can also customize the naming pattern for the resulting segments and the initialization segment as well.

TS

Video Muxings

Audio Muxings

Hint: To optimize your content for a specific use-case you can also provide a custom segment length. Further, you can also customize the naming pattern for the resulting segments and the initialization segment as well.

Step 8: Start EncodingLink Icon

Start Encoding

Recapping, we have defined

  • an input, specifying the input file host
  • an output, specifying where the manifest and the encoded files will be written to
  • codec configurations, specifying how the input file will be encoded
  • streams, specifying which input stream will be encoded using what codec configuration
  • muxings, specifying the containerization of the streams

Now we can start the encoding with one API call:

Step 9: Create a ManifestLink Icon

DASH Manifest

In order to play segmented content, a manifest is required, which contains all the information used by the player to playback the stream.

Create a DASH Manifest

Below we create the DASH manifest resource and add a period to it.

Add Adaptation Sets

Now we are adding a video and audio adaptation set which contain the representations.

Add Representations

Finally we are adding the representations played by the player and starting the manifest generation. The manifest file will be written to the same output as the encoded files.

Start Manifest Generation

Once the encoding has finished and all segments have been written to the output, the manifest generation can be started.

HLS Manifest

In order to play segmented content, a manifest is required, which contains all the information used by the player to playback the stream.

Create a HLS manifest

Below we create the HLS manifest.

Create Variant Stream and Audio Media

Now we are adding the audio media and a variant stream to the HLS manifest.

Start Manifest Generation

Once the encoding has finished and all segments have been written to the output, the manifest generation can be started.

Step 10: Final ReviewLink Icon

You started your first encoding, with a muxing and a manifest. This is only the beginning. The Bitmovin Encoding API is extremely flexible and allows many customizations. Have a look at the documentation to learn more.

ExamplesLink Icon

You can download fully functional code examples from our Github account.

Github

Give us feedback