NAV Navbar
iOS android javascript

Welcome

Welcome to Firekast! The best developer tools to bring live video streaming into your app without being a video expert.

Firekast is a Video as a Service platform, we provide iOS and Android SDKs to wrap camera usage, streaming, video encoding and player into something sweet and easy to use. Yes, you are 5 minutes away to make the next Periscope 😎

We obsesses over developer experience and want this documentation to be as clear as possible. If you have any question, suggestion, feature request, feel free to contact us, we would love to hear from you.

Firekast Basics

Before we start, let's introduce some Firekast basics concepts. You may already be familiar with since we designed our service with well known SaaS platforms in mind.

Nothing in life is to be feared, it is only to be understood. Now is the time to understand more, so that we may fear less. -- Marie Curie

API key

The API key allows you to make a restricted set of calls through our REST API. The API only allows calls to get streams for playback, typically for use with our JS Player.

clientKey

This is your private account key. It is created once you create an account on Firekast dashboard. This key is needed for mobile SDK initialization.

It is available in Firekast dashboard and looks like c8178e40-0ccf-35e7-a17c-5b26c0cf5f87.

Application

On your dashboard, you can create as many applications as you like. An application is identified with its unique applicationId and gathers all the streams you have made using this id.

To create an application, you must specify a name (usually your company name or app name), and specify a plan (free or paying, see pricing). Each of these information can be edited later.

An application can be deleted if you decide so.

applicationId

The id that uniquely identifies an application.

It is available in the Firekast dashboard and looks like e8078520-0ccf-35e7-8493-034e3c17d8c0.

streamId

The id that uniquely identifies a stream in your application. See stream.id.

It is available in the Firekast dashboard, within your application and looks like d17j39tg4noar25g3.

Active users

Each new device (mobile or web) that reaches our server is counted as a new active user once a month.

Installation

1. edit your podfile

use_frameworks!
# Set the same version name X.Y.Z. for both Firekast and VideoCore pod. Here 1.1.0.
pod 'Firekast', :podspec => 'http://firekast.io/sdk/ios/v1.1.0/Firekast.podspec'
pod 'VideoCore', :git => 'https://github.com/Firekast-io/VideoCore.git', :tag => 'fk-1.1.0'

# Please note, first `pod install` may be long, please be patient :)

2. run in terminal

pod install

3. initialize the SDK

import Firekast
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  Firekast.initialize(clientKey: "YOUR_CLIENT_KEY", applicationId: "YOUR_APPLICATION_ID")
}

4. specify camera and microphone usage description in your info.pList

<key>NSCameraUsageDescription</key>
<string>Camera usage description</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone usage description</string>

1. edit your project root build.gradle

allprojects {
    repositories {
        [...]
        maven { url 'https://dl.bintray.com/firekast/android' }
    }
}

2. edit your app build.gradle

dependencies {
    implementation 'io.firekast:firekast:1.0.0'
    implementation 'com.google.android.exoplayer:exoplayer:r1.5.0'
}

3. initialize the SDK

Firekast.initialize(this, "YOUR_CLIENT_KEY", "YOUR_APPLICATION_ID", Log.VERBOSE);

1. import

Option a. script tag

<script src="https://firekast.io/sdk/js/1.0.0/firekast.min.js"></script>

Option b. Webpack, Browserify...

const Firekast = require('firekast');

Option c. AMD module syntax

define(["firekast"], function(Firekast) { 
  //... 
});

2. Initialize the SDK

Firekast.init({
  api_key: 'YOUR_API_KEY'
});

We use common dependency managers to distribute our SDKs and make installation as straightforward as possible.

Cocoapods for iOS, and Gradle for android.

Our javascript SDK is not yet available on the public npm registry. Please, let us know if you would love so.

Getting Started

Live stream

let streamer = FKStreamer() // 1. initializes streamer
let camera = streamer.showCamera(.front, in: myView) // 2. open camera inside myView

streamer.requestStream { (stream, error) in // 3. create a stream
    streamer.startStreaming(on: stream, delegate: self) // 4. start streaming firekast
}
// 1. get fragment from layout
mCameraFragment = (FKCameraFragment) getSupportFragmentManager().findFragmentById(R.id.camera_fragment);
mCameraFragment.getCameraAsync(new FKCameraFragment.OnCameraReadyCallback() {
  @Override
  public void onCameraReady(@Nullable FKCamera camera, @Nullable FKError error) {
    // 2. get camera as soon as it's available
    mCamera = camera; 
  }
});
mStreamer = mCameraFragment.getStreamer();
// 3. create a stream
mStreamer.requestStream(new FKStreamer.RequestStreamCallback() { 
  @Override
  public void done(@Nullable FKStream stream, @Nullable FKError error) {
    // 4. start streaming on firekast
    mStreamer.startStreaming(stream, new MyFKStreamingCallback());
  }
});

The javascript SDK currently only supports live and vod content playback, not publishing.

This is all you need to do to live stream your front camera 👉

First, you must request for a stream and then, call start streaming method whenever your User decides to.

Live stream on social networks simultaneously

let fbLive = FKOutput.facebook(accessToken: "YOUR_FACEBOOK_TOKEN")
let ytLive = FKOutput.youtube(accessToken: "YOUR_YOUTUBE_TOKEN", title: "Awesome title")

streamer.requestStream(outputs: [fbLive, ytLive]) { (stream, error) in // 3. create a stream specifying outputs
    streamer.startStreaming(on: stream, delegate: self) // 4. start streaming on facebook, youtube and firekast
}
FKOutput facebook = FKOutput.facebook("YOUR_TOKEN_FACEBOOK", null);
FKOutput youtube = FKOutput.youtube("YOUR_TOKEN_YOUTUBE", "Awesome title", null);

List outputs = new ArrayList<>();
outputs.add(facebook);
outputs.add(youtube);

// 3. create a stream specifying outputs
mStreamer.requestStream(outputs, new MyFKRequestStreamCallback());

Firekast allows to push your stream to several live streaming platform, such as Facebook or Youtube, simultaneously.

Access camera features

camera.position = .back // open back camera

camera.isMicrophoneEnabled = false // mute microphone

if camera.isFlashAvailable {
    camera.isFlashEnabled = true // turn flash on if available for the current camera
}
mCamera.switchToPosition(Position.BACK); // open back camera

mCamera.setMicrophoneEnabled(false); // mute microphone

if (mCamera.isFlashAvailable()) {
    mCamera.setFlashEnabled(true); // turn flash on if available for the current camera
}

Adding camera often leads to boilerplate codes, especially on Android where you must pay attention on your Activity or Fragment lifecycle.

Our SDK manages everything for you and provides simple interface to interact with commonly used features.

Watch live or replay as VOD

let player = FKPlayer() // 1. initialize player
player.show(in: myView) // 2. display player in myView

player.play(streamId: "THE_STREAM_ID", delegate: self) // 3. play the video 
// 1. add the player in your layout
<io.firekast.FKPlayerView
    android:id="@+id/videoView"
    android:layout_width="200dp"
    android:layout_height="110dp" />

// 2. listen for player callback (optional) and play the video
mVideoView.setPlayerListener(new MyFKPlayerCallback());
mPlayerView.play("THE_STREAM_ID");

The player wraps around clappr.

  <div id="player"></div>
  <script>
    Firekast.API.init({
                api_key: 'YOUR_API_KEY'
            });
    const player = new Firekast.Player({
                parent_id:   '#player',
                stream_id:   'THE_STREAM_ID'
            });
  </script>

The player will figure out whether the stream is live or vod and will adapt the player UI accordingly.

SDK | Stream

Our APIs can be used on your backend to list your streams and manage your applications.

Contact us to discuss your needs.

A stream describes one video content. A stream is unique and is associated to an application.

id

This is the unique id of the object, see streamId. It is assigned when the Stream object is created.

state

During its life time, a stream goes though different states:

Stream's lifecycle can be either:

SDK | Streamer

The javascript SDK currently only supports live and vod content playback, not publishing.

The streamer handles the stream creation and let you stream on your application.

Request for a stream

streamer.requestStream()
mStreamer.requestStream(new MyFKRequestStreamCallback());

Before being able to start streaming, you must request for a stream. This will create a stream on Firekast server.

This new created stream is immediatly visible in your dashboard.

Specify outputs

streamer.requestStream(outputs: [])
mStreamer.requestStream(listOfOutputs, new MyFKRequestStreamCallback());

Firekast lets you push your live stream to several live streaming platform, such as Facebook or Youtube, simultaneously.

If you want to repush on social networks, you must provide corresponding information so the server create a special stream.

Start and stop streaming

Start streaming

streamer.startStreaming(on: stream, delegate: self)
mStreamer.startStreaming(stream, new MyFKStreamingCallback());

Stop streaming

streamer.stopStreaming()
mStreamer.stopStreaming()

Once you have created a stream, you can start streaming whenever your User is ready.

Listen for events while streaming

func streamer(_ streamer: FKStreamer, willStartOn stream: FKStream?, unless error: FKError?) {
  // ...
}

func streamer(_ streamer: FKStreamer, didStopOn stream: FKStream?, error: FKError?) {
  // ...
}

func streamer(_ streamer: FKStreamer, networkQualityDidUpdate rating: Float) {
  // ...
}
private class MyStreamingCallback implements FKStreamer.StreamingCallback {
  @Override
  public void onSteamWillStartUnless(@Nullable FKStream stream, @Nullable FKError error) {
    // ...
  }

  @Override
  public void onStreamDidStop(FKStream stream, FKError error) {
    // ...
  }

  @Override
  public void onStreamingUpdateAvailable(boolean lag) {
    // ...
  }
}

When start streaming you might want to adapt your UI depending on events. You will be notified whether the streaming starts properly, stops normally or prematurely, and streaming conditions.

SDK | Player

The player lets you play any stream of your current application. Whether the stream is live or VOD, the player will figure it out and adapt its UI.

Initialization

The player is a wrap arount MPMoviePlayerController, and is even simpler to use.

override func viewDidLoad() {
  super.viewDidLoad()
  player = FKPlayer()
  player.show(in: playerContainerView)
}

The player is based on ExoPlayer and is wrapped into a simple view.

<io.firekast.FKPlayerView
  android:id="@+id/videoView"
  android:layout_width="match parent" 
  android:layout_height="110dp" />

The player wraps around clappr.

  <div id="player"></div>
  <script>
    Firekast.API.init({
                api_key: 'YOUR_API_KEY'
            });
    const player = new Firekast.Player({
                parent_id:   '#player',
                stream_id:   'THE_STREAM_ID'
            });
  </script>

For each platform, we wrap the most common player so we expose only methods that count.

Play and stop

player.play(streamId: "THE_STREAM_ID", delegate: self)
player.stop()
mPlayerView.play("THE_STREAM_ID");
mPlayerView.stop();
player.on('ready', () => {
  player.play();
});
player.stop();

The following methods are also available.

player.pause()
player.seek(seconds:Number)
player.mute()
player.setVolume(percent:Number)
player.getCurrentTime():Number
player.getDuration():Number
player.isPlaying():Boolean
player.destroy()

The player aims to be very simple.

Call play by providing the streamId. The player will first fetch the stream, determines whether it's live or vod, and starts to play.

The playback controller UI automatically adapts whether the player is playing a live or vod stream.

Listen for player events

func player(_ player: FKPlayer, stateDidChanged state: FKPlayer.State) {
  // ...
}

func player(_ player: FKPlayer, videoDurationIsAvailable duration: TimeInterval) {
  // ...
}

func player(_ player: FKPlayer, willPlay stream: FKStream?, unless error: FKError?) {
  // ...
}
mPlayerView = (FKPlayerView) findViewById(R.id.videoView);
mPlayerView.setPlayerListener(new FKPlayerView.Callback() {
  @Override
  public void onPlayerWillPlay(@Nullable FKStream stream, @Nullable FKError error) {
    // ...
  }
});
const events = [
  'ready',
  'play',
  'stop',
  'ended',
  'error',
  'timeupdate',
  'volumechange',
  'seek',
  'resize'
];

events.forEach( event => {
  player.on('ready', () => console.log(`Player emitted ${event}`));
});

player.on('ready', () => player.play());

You may want to listen for player callback so you can adapt adapt your UI accordingly. Indeed, since the stream is fetched internally to determine whether its live, vod, etc... the request can fail. There is no retry strategy so you may notify your user about the failure.