BB Player for Flutter

A Flutter plugin for Blue Billywig video player. Provides native video playback with ads, analytics, and Chromecast support.

New to BB Player? Check out our Getting Started Guide for a complete walkthrough.

Features

• Native video playback using Blue Billywig's SDK
• Full playback controls (play, pause, seek, volume)
• Fullscreen support
• Ad support (pre-roll, mid-roll, post-roll)
• Analytics events
• Chromecast support
• Shorts (vertical video) player
• Outstream ad placements with animated collapse/expand

Installation

Add this to your pubspec.yaml:

dependencies:
  bb_player:
    git:
      url: https://github.com/bluebillywig/flutter-bb-player.git

iOS Setup

Minimum iOS deployment target is 14.0. For CocoaPods apps, set it in your ios/Podfile:

platform :ios, '14.0'

Swift Package Manager (Flutter 3.44+)

This plugin ships an SPM manifest (ios/bb_player/Package.swift) in addition to the CocoaPods podspec, so apps on Flutter 3.44 or newer (where SPM is the default) resolve bb_player — and the native BlueBillywigNativePlayerKit-iOS (Google Cast bundled) — via Swift Package Manager. On older Flutter / CocoaPods apps the manifest is dormant and the podspec is used, so the 3.32 CocoaPods floor is unaffected.

CocoaPods mode stops at the last kit on CocoaPods Trunk. Trunk goes read-only on 2 December 2026 and no new native kit reaches it after that. The podspec pins the exact kit of each plugin release, so from the first plugin release built on a newer kit, pod install in CocoaPods mode fails with a "could not find compatible versions" error for BlueBillywigNativePlayerKit-iOS. Switch the app to Swift Package Manager (Flutter 3.44+: flutter config --enable-swift-package-manager) to keep upgrading.

Consume from a directory named bb_player. SPM derives a path-package's identity from its directory name, which must match the package name (bb_player). When using a local path: dependency or a CI sibling checkout, place this repo in a directory called bb_player (e.g. actions/checkout with path: bb_player), not flutter-bb-player.

Android Setup

Make sure your android/build.gradle includes the standard repositories — the Blue Billywig SDK is published to Maven Central:

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

Usage

Basic Player

import 'package:bb_player/bb_player.dart';

BBPlayerView(
  jsonUrl: 'https://demo.bbvms.com/p/native_sdk/c/4256593.json',
  onPlay: () => print('Playing'),
  onPause: () => print('Paused'),
)

With Controller

BBPlayerController? _controller;

BBPlayerView(
  jsonUrl: 'https://demo.bbvms.com/p/native_sdk/c/4256593.json',
  enableTimeUpdates: true,
  onControllerCreated: (controller) {
    _controller = controller;
  },
  onTimeUpdate: (currentTime, duration) {
    print('Progress: $currentTime / $duration');
  },
)

// Control playback
await _controller?.play();
await _controller?.pause();
await _controller?.seek(30.0);
await _controller?.setVolume(0.5);

// Query state
final duration = await _controller?.getDuration();
final state = await _controller?.getPlayerState();

Shorts Player

For TikTok-style vertical video:

BBShortsView(
  jsonUrl: 'https://demo.bbvms.com/sh/58.json',
  onError: (error) => print('Error: $error'),
)

Outstream Ads

For animated outstream ad placements:

final _outstreamKey = GlobalKey<BBOutstreamViewState>();

BBOutstreamView(
  key: _outstreamKey,
  jsonUrl: 'https://demo.bbvms.com/p/outstream/c/123.json',
  expandedHeight: 250,
  collapsedHeight: 0,
  onCollapsed: () => print('Ad collapsed'),
  onExpanded: () => print('Ad expanded'),
)

// Programmatic control
_outstreamKey.currentState?.collapse();
_outstreamKey.currentState?.expand();

API Reference

BBPlayerView

Property	Type	Description
jsonUrl	String?	URL to player configuration JSON
jwt	String?	JWT token for authenticated content
options	Map<String, dynamic>?	Player options
enableTimeUpdates	bool	Enable periodic time update events
onControllerCreated	Function(BBPlayerController)	Called when controller is ready

BBPlayerController Methods

Playback:

• play() - Start playback
• pause() - Pause playback
• seek(double position) - Seek to position in seconds
• seekRelative(double offset) - Seek relative to current position
• setMuted(bool muted) - Set muted state
• setVolume(double volume) - Set volume (0.0 to 1.0)

Fullscreen:

• enterFullscreen() - Enter fullscreen
• enterFullscreenLandscape() - Enter fullscreen in landscape
• exitFullscreen() - Exit fullscreen

Content Loading:

• loadClip(String clipId, [LoadClipOptions? options]) - Load clip by ID
• loadWithJsonUrl(String url, {bool? autoPlay}) - Load from JSON URL
• loadWithClipListId(...) - Load clip list
• loadWithProjectId(...) - Load project

State Queries:

• getDuration() - Get duration in seconds
• getCurrentTime() - Get current position
• getMuted() - Get muted state
• getVolume() - Get volume level
• getState() - Get player state
• getPhase() - Get player phase
• getClipData() - Get current clip data
• getPlayerState() - Get complete state snapshot

Events

The player emits 40+ events including:

• Playback: onPlay, onPause, onPlaying, onEnded
• State: onStateChange, onPhaseChange, onDurationChange
• Time: onTimeUpdate, onSeeked, onSeeking
• Content: onMediaClipLoaded, onProjectLoaded
• Ads: onAdStarted, onAdFinished, onAdError, onAdQuartile1-3
• Fullscreen: onFullscreen, onRetractFullscreen
• Analytics: onViewStarted, onViewFinished, onCustomStatistics

Documentation

• Getting Started Guide - Complete setup and integration walkthrough
• Blue Billywig Help Center - Native SDK documentation
• Playout Settings - Configure player behavior
• Instream Ads - Video advertising setup
• Outstream Ads - Outstream ad configuration

Support

• Technical issues: support@bluebillywig.com
• Bug reports: GitHub Issues

License

MIT License - see LICENSE file for details.