Package-level declarations

Integrating the Amino Sandboxed Player Library

This guide outlines how to integrate the sandboxed-player-v0.1.0.aar library from Amino Communications into an Android application for media playback with event-driven control. The library provides the SandboxedPlayer class for managing playback, the PlayerEvent class for handling lifecycle events, and the SystemUtil class for retrieving device-specific information such as serial number (SN) and MAC address on Amino devices.

Prerequisites

  • AOSP Firmware: Minimum API level 30 (Android 11).

  • Dependencies: AndroidX Core, AppCompat, and LiveData libraries.

  • AAR File: sandboxed-player-v0.1.0.aar provided by Amino Communications.

Setup

Step 1: Extract the ZIP and Add the AAR

The library is distributed in a ZIP file with the following structure:

library/
├── docs/
└── sandboxed-player-v0.1.0.aar

Copy library/sandboxed-player-v0.1.0.aar into your app module’s directory, typically under app/aar/. Example structure after copying:

app/
├── aar/
│ └── sandboxed-player-v0.1.0.aar
├── src/
└── build.gradle

Step 2: Configure Dependencies

Update your app’s build.gradle (located in app/) to include the AAR and required dependencies:

dependencies {
implementation(libs.androidx.core.ktx)
implementation(libs.androidx.appcompat)
// Amino Sandboxed Player library
implementation(files("./aar/sandboxed-player-v0.1.0.aar"))
}

Sync your project with Gradle files to resolve the dependencies.

Usage

Minimal Example: Waiting for Observer Before Loading Video Source

This example shows how to initialize a SandboxedPlayer, wait for its readiness via an observer, and then load a video source. The setObserver method uses LiveData to signal when the player is ready, ensuring loadVideoSource is called only after preparation is complete.

package com.example.myapp;

import android.os.Bundle;
import android.util.Log;
import android.view.SurfaceView;
import androidx.appcompat.app.AppCompatActivity;
import androidx.lifecycle.Observer;
import com.aminocom.libplayer.SandboxedPlayer;
import com.aminocom.libplayer.PlayerEvent;

public class MainActivity extends AppCompatActivity {
private SandboxedPlayer player;

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

SurfaceView surfaceView = findViewById(R.id.surfaceView1);
player = new SandboxedPlayer(this, surfaceView);

// Set observer to wait for player readiness
Observer<Boolean> readinessObserver = isReady -> {
if (isReady) {
player.loadVideoSource("http://demo-dash-vod.zahs.tv/exodus/manifest.mpd", null);
}
};
player.setObserver(this, readinessObserver);

// Optional: Log playback start for confirmation
player.addEventListener((event, bundle) -> {
if (event.equals(PlayerEvent.PLAYBACK_STARTED)) {
Log.d("PlayerEvent", "Playback started");
}
});
}

@Override
protected void onDestroy() {
super.onDestroy();
player.release();
}
}

Supported Stream Formats and Examples

The SandboxedPlayer library supports a variety of streaming protocols and formats. Below are the supported stream types, their expected URI formats, and usage examples. Some formats require additional configuration via a Bundle passed to SandboxedPlayer.loadVideoSource(String url, Bundle extras).

Dolby Millicast

  • Format: dolbyio://<acc_id>/<stream_name>?token=<token>

  • Description: Streams from Dolby Millicast real-time streaming service. The acc_id is the account ID, and stream_name identifies the stream. An optional token parameter can be appended for authentication.

  • Example: dolbyio://k9Mwad/multiview

  • Usage: Loads the multiview stream under account k9Mwad without a token.

player.loadVideoSource("dolbyio://k9Mwad/multiview", null);

ABR (DASH and HLS)

  • Format: http(s)://{server}/{playlist_path}

  • Description: Adaptive Bitrate Streaming using MPEG-DASH or HLS playlists over HTTP/HTTPS. The playlist_path points to a manifest (.mpd for DASH, .m3u8 for HLS).

  • Example: http://www.aminocom.com/videos/playlist.mpd

  • Usage: Loads a DASH manifest from the specified host.

player.loadVideoSource("http://www.aminocom.com/videos/playlist.mpd", null);

DASH with Widevine

  • Format: http(s)://{server}/{playlist_path}

    • encryption_type: Specifies Widevine DRM (com.widevine.alpha).

    • encrypting_server: URL of the Widevine license server.

  • Description: DASH streams with Widevine DRM encryption. Requires a Bundle with encryption details, including the Widevine DRM type and license server URL.

  • Example: http://www.aminocom.com/videos/sample_enc.mpd

  • Usage: Loads an encrypted DASH stream with Widevine protection.

Bundle bundle = new Bundle();
bundle.putString("encryption_type", "com.widevine.alpha");
bundle.putString("encrypting_server", "http://demo.aminocom.com/license");
player.loadVideoSource("http://www.aminocom.com/videos/sample_enc.mpd", bundle);

HTTP Progressive

  • Format: http(s)://{server}/{file_path}

  • Description: Progressive download of a single media file (e.g., MP4) over HTTP/HTTPS.

  • Example: http://example.com/video.mp4

  • Usage: Loads an MP4 file for progressive playback.

player.loadVideoSource("http://example.com/video.mp4", null);

Multicast

  • Format: udp://{address}:{port}

  • Description: Multicast streams over UDP, specifying the IP address and port.

  • Example: udp://233.22.133.100:8110

  • Usage: Loads a multicast stream from the specified UDP address and port.

player.loadVideoSource("udp://233.22.133.100:8110", null);

RTSP

  • Format: rtsp://{server}/{asset}

  • Description: Real-Time Streaming Protocol streams, typically for live or on-demand content from an RTSP server.

  • Example: rtsp://www.domain.com:554/stream.ts

  • Usage: Loads an RTSP stream from the specified server.

player.loadVideoSource("rtsp://www.domain.com:554/stream.ts", null);

RTMP

  • Format: rtmp://{server}/{path}

  • Description: Real-Time Messaging Protocol streams, commonly used for live streaming.

  • Example: rtmp://www.domain.com/stream/path

  • Usage: Loads an RTMP stream from the specified server and path.

player.loadVideoSource("rtmp://www.domain.com/stream/path", null);

Event System

Events are dispatched in a typical order:

  1. BUFFERING: Data delays playback.

  2. METADATA_LOADED: Metadata available.

  3. BUFFERING_ENDED: Buffering resolved.

  4. READY_TO_START: Playback prerequisites met.

  5. PLAYBACK_STARTED: First frame rendered.

  6. PLAYBACK_ENDED: Playback ends.

Note: BUFFERING_ENDED may precede METADATA_LOADED if buffering resolves first. DECRYPTION_FAIL and ERROR can occur anytime with Bundle details.

Types

Link copied to clipboard
public class PlaybackInfo
Data class representing playback information for a media player instance.
Link copied to clipboard
public class PlayerEvent
Constants defining external events dispatched by the player to registered listeners.
Link copied to clipboard
public interface PlayerEventListener
Interface for receiving events from a media player instance.
Link copied to clipboard
public class SandboxedPlayer implements PlayerInterface
This class handles video rendering on a SurfaceView and provides control over playback, audio, events, and readiness state.
Link copied to clipboard
public class SystemUtil
A utility class that binds to a generic service to provide access to INI configuration and device information.
Link copied to clipboard
public class TrackInfo
Represents information about tracks available in a media player instance.