Welcome

With Pixels.IO SDK, your Android app can embed Video Response Codes in video content. This enables creation of seamless interactive and multi-screen content.

How it works?

The core of the SDK is the VideoPlayer -- a MediaPlayer-like View which adds on-the-fly embedding of Video Response Codes. Each video played through this player, can be annotated with destination URLs which are used by the VRCode decoder to direct the user to the related content. The URL annotation can be performed in the back-office or via the SDK within the app.

Uploading videos to the back-office

Before the video can be used in the VideoPlayer, it must first be processed in the back-office. Log into the back-office and click + Add Video to upload your video file. After uploading, set the Name of the video so that it can be used within the VideoPlayer. The video will then be analyzed for optimal embedding of Video Response Codes, and you will receive an email when the video is ready for use in the VideoPlayer.

Note

The video file is uploaded to the back-office only for VRCode analysis. To play it in your app, you will need to either store it on the device or host it online.

Displaying videos

In your Android application project, add the Pixels.IO SDK library as a dependency. Then create a VideoPlayer within an Activity or a Fragment of your choosing. To construct a VideoPlayer, you will need the API Key listed in the back-office. Note that in order to receive asynchronous callbacks, you must construct the VideoPlayer on a thread with a Looper. See the VideoPlayer class reference for details.

public class MyActivity extends Activity {
  private static String MY_API_KEY = "my key"; // use your API Key from the back-office

  protected void onCreate(...) {
    VideoPlayer player = new VideoPlayer(this, MY_API_KEY);
  }
}

To make the video appear within your app view hierarchy, add its view to your layout:

  protected void onCreate(...) {
    ...
    setContentView(player.getView());
  }

It is also a good idea to listen for any errors that the player might encounter by providing an OnErrorListener:

  player.setOnErrorListener(new VideoPlayer.OnErrorListener() {
    @Override
    public void onError(Exception exception) {
      // handle the error
      Log.e("MyActivity", "something went wrong", exception);
    }
  });

Next, tell the player to prepare for displaying a specific video source using VideoPlayer.prepare. The video path can be anything that is accepted by the Android MediaPlayer, whether it is a network data source or a locally stored data file. The name of the video should match the Name specified in the back-office.

  player.prepare("/sdcard/myvideo.mp4", "my video", myPrepareListener);

This call completes asynchronously and your listener will receive a VideoPlayer.Item which can be then passed to VideoPlayer.start.

  myPrepareListener = new VideoPlayer.OnPreparedListener {
    @Override
    public void onPrepared(VideoPlayer player, VideoPlayer.Item item) {
      // the item is now ready for playback, you can store it somewhere or play immediately
      player.play(item);
    }
  });

The VideoPlayer supports common playback commands such as pause, resume, stop, isPlaying, seekTo. The difference between pause and stop is that after pause the view will display a still video frame. You can also listen for completion of playback via VideoPlayer.setOnCompletedListener. This allows easy looping of a single video or going through a playlist of videos:

  player.setOnCompletedListener(new VideoPlayer.OnCompletedListener {
    @Override
    public onCompleted(VideoPlayer player, VideoPlayer.Item item) {
      // play the next item from your playlist or just loop the same item
      player.play(item);
    }
  });

Annotating videos with URLs

The destination URL is used by the VRCode decoder to direct the user to related content. There is a few different ways to specify the destination URL:

Via the back-office

You can provide a Default URL within the back-office. Click on the video to edit it. The change takes effect immediately and will apply to all players that play the video. However, any URL specified within the SDK will override this default.

Via the SDK

The VideoPlayer allows setting the destination URL specific to the particular device playing the video. This means, different devices can use different URLs even when playing the same video at the same time. The simplest way to do this is by calling VideoPlayer.setUrl:

  player.setUrl("http://example.com/my_url_specific_to_this_device");

Subsequently, this URL will be used for all videos played through the player, until this setting is changed or reset by passing null or the empty String ("") for the URL:

  player.setUrl("");

If you have a long video where multiple different URLs would be relevant throughout the playback, you can set more specific URLs for each part of the video. Calling addUrlAt sets the URLs to be used starting from a particular playback position in the video item. This URL will be used until the end of the video or the next position specified via addUrlAt. If you want to go back to the default URL starting from a particular position, you can pass the empty String ("") for the URL.

  // Set a custom destination URL beginning at 10 seconds into the video.
  item.addUrlAt(10000, "http://example.com/page_for_the_second_part");
  // Go back to the default URL 20 seconds later.
  item.addUrlAt(30000, "");

If you want to remove some URLs specified with addUrlAt you will need to first remove all of them using clearUrls. See the VideoPlayer.Item class reference for details.

Requirements

The SDK requires:

Note

VideoPlayer depends on accurate location. If you are targetting Android 6.0+ (targetSdkVersion 23), the Activity also needs to request permission from the user at runtime (rather than during installation).