expo-bb-player

React Native implementation of the Blue Billywig Outstream Native Player for Expo and bare React Native apps.

Installation

For Expo Managed Projects

If you're using an Expo managed project (created with create-expo-app), simply install the package:

npx expo install expo-bb-player

Then run prebuild to generate native directories:

# For iOS
npx expo prebuild -p ios

# For Android
npx expo prebuild -p android

For Bare React Native Projects

Prerequisites

This library is an Expo module, so you need to have Expo modules installed in your project first. If you haven't installed Expo modules yet, follow these steps:

1. Automatic Setup (Recommended):

npx install-expo-modules@latest

This command will automatically configure your project to use Expo modules. For more details, see the official Expo documentation.

2. Manual Setup:

If the automatic installation fails, follow the manual installation guide in the Expo documentation.

Installing expo-bb-player

Once Expo modules are installed in your project:

1. Install the package:

npx expo install expo-bb-player
# or
npm install expo-bb-player

2. For iOS, install CocoaPods dependencies:

npx pod-install

3. For Android, the dependencies will be automatically linked through autolinking.

4. Rebuild your app:

# For iOS
npx expo run:ios
# or
npx react-native run-ios

# For Android
npx expo run:android
# or
npx react-native run-android

Basic Usage

Here's a simple example of how to use the Blue Billywig Player:

import React, { useRef } from 'react';
import { View, StyleSheet, Button } from 'react-native';
import { ExpoBBPlayerView, type ExpoBBPlayerViewType } from 'expo-bb-player';

export default function App() {
  const playerRef = useRef<ExpoBBPlayerViewType>(null);

  return (
    <View style={styles.container}>
      <ExpoBBPlayerView
        ref={playerRef}
        jsonUrl="YOUR_BLUE_BILLYWIG_JSON_URL"
        options={{
          autoPlay: false,
          allowCollapseExpand: true,
        }}
        onDidTriggerPlay={() => {
          console.log('Player started playing');
        }}
        onDidTriggerPause={() => {
          console.log('Player paused');
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
  },
});

Advanced Example

Here's a more advanced example with event handlers and player controls:

import React, { useRef, useState } from 'react';
import { View, StyleSheet, Button, Text } from 'react-native';
import { 
  ExpoBBPlayerView, 
  type ExpoBBPlayerViewType,
  type State,
  type Phase 
} from 'expo-bb-player';

export default function AdvancedPlayer() {
  const playerRef = useRef<ExpoBBPlayerViewType>(null);
  const [playerState, setPlayerState] = useState<State>('IDLE');
  const [playerPhase, setPlayerPhase] = useState<Phase>('INIT');
  const [duration, setDuration] = useState(0);

  const handleEnterFullscreen = () => {
    playerRef.current?.enterFullscreen();
  };

  const handleSeek = (position: number) => {
    playerRef.current?.seek(position);
  };

  const handleSetVolume = (volume: number) => {
    playerRef.current?.setVolume(volume);
  };

  return (
    <View style={styles.container}>
      <ExpoBBPlayerView
        ref={playerRef}
        jsonUrl="YOUR_BLUE_BILLYWIG_JSON_URL"
        options={{
          autoPlay: true,
          autoMute: false,
          allowCollapseExpand: true,
        }}
        onDidTriggerStateChange={(state) => {
          setPlayerState(state);
          console.log('State changed:', state);
        }}
        onDidTriggerPhaseChange={(phase) => {
          setPlayerPhase(phase);
          console.log('Phase changed:', phase);
        }}
        onDidTriggerDurationChange={(duration) => {
          setDuration(duration);
          console.log('Duration:', duration);
        }}
        onDidTriggerProjectLoaded={(project) => {
          console.log('Project loaded:', project);
        }}
        onDidTriggerMediaClipLoaded={(mediaClip) => {
          console.log('Media clip loaded:', mediaClip);
        }}
        onDidFailWithError={(error) => {
          console.error('Player error:', error);
        }}
        onDidTriggerAdStarted={() => {
          console.log('Ad started');
        }}
        onDidTriggerAdFinished={() => {
          console.log('Ad finished');
        }}
      />
      <View style={styles.info}>
        <Text>State: {playerState}</Text>
        <Text>Phase: {playerPhase}</Text>
        <Text>Duration: {duration.toFixed(2)}s</Text>
      </View>
      <View style={styles.controls}>
        <Button title="Fullscreen" onPress={handleEnterFullscreen} />
        <Button title="Seek to 10s" onPress={() => handleSeek(10)} />
        <Button title="Volume 50%" onPress={() => handleSetVolume(0.5)} />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
  },
  info: {
    padding: 20,
    backgroundColor: '#f0f0f0',
  },
  controls: {
    flexDirection: 'row',
    justifyContent: 'space-around',
    padding: 20,
  },
});

API Reference

Props

Prop	Type	Description
jsonUrl	string	The Blue Billywig JSON URL for the media
options	Record<string, unknown>	Player configuration options passed through to the native SDK
style	ViewStyle	Styling for the player container
Event props	See Events	Subscribe to native player events (see Events section below)

Player Options

Common options you can pass to the options prop:

{
  autoPlay: boolean;           // Auto-play the video
  allowCollapseExpand: boolean; // Allow collapse/expand functionality
  autoLoop: boolean;            // Loop the video

}

Methods

Access these methods via the player ref:

// Playback controls
play(): Promise<void>
pause(): Promise<void>
seek(position: number): Promise<void>

// Volume controls
setVolume(volume: number): Promise<void>  // 0.0 - 1.0
setMuted(muted: boolean): Promise<void>

// Fullscreen controls
// Android: implemented. iOS: currently no-op.
enterFullscreen(): Promise<void>
exitFullscreen(): Promise<void>

// Expand/Collapse controls (outstream sizing)
expand(): Promise<void>
collapse(): Promise<void>

// Ad/clip data
adMediaHeight(): Promise<number | undefined>
adMediaWidth(): Promise<number | undefined>
adMediaClip(): Promise<MediaClip | undefined>
autoPlayNextCancel(): Promise<void>

// State getters
playerState(): Promise<State>
phase(): Promise<Phase>
duration(): Promise<number | undefined>
volume(): Promise<number | undefined>
muted(): Promise<boolean | undefined>
inView(): Promise<boolean | undefined>
mode(): Promise<string | undefined>
controls(): Promise<boolean | undefined> // Android only; iOS returns undefined
playoutData(): Promise<Playout | undefined>
projectData(): Promise<Project | undefined>

Platform notes:

• iOS: enterFullscreen and exitFullscreen are currently not supported.
• iOS: controls() is not exposed by the native SDK and will return undefined.

Events

All events below are exposed as optional props on ExpoBBPlayerView. Payload types are indicated in parentheses.

Event	Payload	Description
onDidFailWithError	string	A fatal or setup error occurred
onDidRequestCollapse	-	Player requested to collapse (outstream)
onDidRequestExpand	-	Player requested to expand (outstream)
onDidRequestOpenUrl	string	Player requested to open a URL
onDidSetupWithJsonUrl	string	Player finished initial setup with the provided JSON URL
onDidTriggerCanPlay	-	Player is ready; API getters should now be available
onDidTriggerPlay	-	Playback started
onDidTriggerPause	-	Playback paused
onDidTriggerPlaying	-	Playback is progressing
onDidTriggerEnded	-	Playback ended
onDidTriggerStateChange	State	Player state changed
onDidTriggerPhaseChange	Phase	Player phase changed
onDidTriggerDurationChange	number	Media duration changed
onDidTriggerVolumeChange	number	Volume changed
onDidTriggerSeeked	number	Seek completed to the provided position (seconds)
onDidTriggerSeeking	-	Seek started
onDidTriggerFullscreen	-	Entered fullscreen
onDidTriggerRetractFullscreen	-	Exited fullscreen
onDidTriggerModeChange	string	Player mode changed
onDidTriggerProjectLoaded	Project	Project loaded
onDidTriggerMediaClipLoaded	MediaClip	Media clip loaded
onDidTriggerMediaClipFailed	-	Media clip failed to load
onDidTriggerStall	-	Playback stalled
onDidTriggerCustomStatistics	{ ident: string; ev: string; aux: Record<string,string>; }	Custom statistics event
onDidTriggerAutoPause	Android: string (why) · iOS: void	Auto-pause was triggered
onDidTriggerAutoPausePlay	Android: string (why) · iOS: void	Auto-pause resume was triggered
onDidTriggerAdLoadStart	-	Ad load started
onDidTriggerAdLoaded	-	Ad loaded
onDidTriggerAdStarted	-	Ad started
onDidTriggerAdQuartile1	-	Ad reached 25%
onDidTriggerAdQuartile2	-	Ad reached 50%
onDidTriggerAdQuartile3	-	Ad reached 75%
onDidTriggerAdFinished	-	Ad finished
onDidTriggerAdNotFound	-	No ad was available
onDidTriggerAdError	string	Ad-related error
onDidTriggerAllAdsCompleted	-	All ads completed
onDidTriggerViewStarted	-	View tracking started
onDidTriggerViewFinished	-	View tracking finished

Platform notes:

• Android and iOS emit the full set of events above. On iOS, onDidTriggerAutoPause and onDidTriggerAutoPausePlay do not include the why payload, while on Android the why string is provided.
• Some events are emitted only when relevant (e.g., ad-related events only during ad playback).

Types

type State = "IDLE" | "LOADING" | "PLAYING" | "PAUSED" | "ERROR";
type Phase = "INIT" | "PRE" | "MAIN" | "POST" | "EXIT";
// Selected payload types used in events and getters
type CustomStatistics = { ident: string; ev: string; aux: Record<string, string> };
type Project = { /* see src/types.ts for full shape */ };
type MediaClip = { /* see src/types.ts for full shape */ };
type Playout = { /* see src/types.ts for full shape */ };

SDK Version Management

This package automatically uses the latest compatible version of the Blue Billywig native SDKs:

• iOS: Version ~>8.30
• Android: Version range [8.30,9.0)

Automatic Updates

When you run pod install (iOS) or build your Android app, the build system will automatically resolve to the latest available version within these constraints. This ensures you benefit from bug fixes and improvements in the native SDKs without manual intervention.

iOS: Uses CocoaPods pessimistic versioning (~>8.30), which allows any version from 8.30 up to (but not including) 9.0.

Android: Uses Gradle range notation ([8.30,9.0)), which allows any version from 8.30 (inclusive) to 9.0 (exclusive).

Version Constraints

The minimum version constraint of 8.30 ensures users have access to the latest features and critical fixes. When we release version 9.0, we will update this package to support it.

For Package Maintainers

The lockfiles (Podfile.lock and Gemfile.lock) are intentionally not committed to version control. This ensures that:

1. End users always get the latest SDK versions within the specified constraints
2. SDK updates flow through automatically without requiring package updates
3. CI/CD builds catch any breaking changes early

Example Project

Check out the /example directory for a complete working example with:

• Multiple player configurations
• Event handling demonstrations
• API usage examples

To run the example:

cd example
npm install

# For iOS
npx expo run:ios

# For Android
npx expo run:android