FastPix player for Flutter

The FastPix Flutter Player SDK makes it easy to add video playback to your Flutter app. Whether you’re streaming live events or on-demand content, it’s built to handle both with smooth performance. It’s designed specifically for FastPix video streams and integrates cleanly into Flutter workflows, ensuring a smooth and dynamic video playback experience.

You can use the GitHub repository for FastPix Flutter player.

Step 1: Set up media in FastPix

Before writing a single line of Flutter code, you’ll need a playback ID. This is how FastPix identifies which video to stream. The SDK doesn’t care whether your video is live or on-demand, private or public - it just needs that ID.

Here’s how to generate it:

1. Log into the FastPix Dashboard using your credentials.
2. Create a media asset. You can do this using either the “Push” (you upload to FastPix) or “Pull” (FastPix fetches from your source URL) methods.
3. If you’re building this into an automated workflow, you can use the FastPix API to create assets programmatically.
4. Once the asset is created, go to the “View Media” page.
5. From there, locate the Playback ID. This is what you’ll plug into the Flutter player to stream this video.

PLEASE NOTE

Playback IDs are case-sensitive, and each one maps to a single video stream. If your video is protected, you'll also need to generate a valid JWT token with appropriate access claims.

Step 2: Install the Flutter player SDK

Installing the SDK is straightforward. You’ll use Flutter’s pub tool to add the fastpix_video_player dependency to your app.

You have two options here:

Option A: Add via terminal

flutter  pub  add  fastpix_video_player 

Option B: Add the dependency directly

Alternatively, you can add the dependency directly in your pubspec.yaml

dependencies: 
	fastpix_video_player: 1.0.0 

Then run:

flutter  pub  get 

PLEASE NOTE

If you’re behind a proxy, or using a CI/CD runner, confirm that the SDK is being correctly fetched and cached. You can always verify installation by running flutter pub deps.

Step 3: Import the SDK to your project

Now that the SDK is installed, you need to import it into any Dart file where you want to use FastPix player components. Typically, this will be in a page or file where where you’ll implement video playback features - like your main.dart or any feature module.

At the very top of the file, add the import statement:

// Import FastPix Flutter Player SDK into Dart files 
import  'package:fastpix_player/fastpix_video_player.dart'; 

This import statement ensures that all the classes, methods, and functionalities provided by the FastPix Flutter Player SDK are available for use in your project.

Step 4: Play a video in your app

Once the SDK is imported, you can begin working with its APIs. This includes initializing the player, configuring playback options, and handling video streams.

You can now leverage the Flutter Player SDK to configure a player controller for streaming a FastPix media using just the playback ID that was generated for the video that you uploaded to FastPix.

4.1 Create a data source

This is the core object that tells the player what to play. You’ll provide:

• The playbackId
• Stream type (live or on-demand)
• Optional: title, description, thumbnail, token, custom domain

final dataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  title: 'Sample HLS Stream', 
  description: 'A sample HLS stream from FastPix', 
  thumbnailUrl: 'https://www.example.com/thumbnail.jpg', 
); 

4.2 Define Player Configuration

This controls how the player behaves - autoplay settings, quality preferences, controls, etc.

final configuration = FastPixPlayerConfiguration(); 

4.3 Initialize the Controller

This connects your data source and config to the actual player.

controller = FastPixPlayerController(); 
controller.initialize(dataSource: dataSource, configuration: configuration); 

4.4 Render the Player

Finally, use the FastPixPlayer widget in your layout. You can control width, height, aspect ratio, and loading indicators.

return FastPixPlayer( 
  controller: controller, 
  width: 350, 
  height: 200, 
  aspectRatio: FastPixAspectRatio.ratio16x9, 
); 

PLEASE NOTE

Always dispose the controller in dispose() when the widget is removed. Forgetting this can lead to memory leaks, especially on Android.

Detailed usage example

mport 'package:fastpix_player/fastpix_video_player.dart'; 
import 'package:flutter/material.dart'; 

void main() { 
  runApp(const MyApp()); 
} 
 
class MyApp extends StatelessWidget { 
  const MyApp({super.key}); 
 
  // This widget is the root of your application. 
  @override 
  Widget build(BuildContext context) { 
    return MaterialApp( 
      title: 'Fastpix Player Demo', 
      theme: ThemeData( 
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple), 
      ), 
      home: const FastPixPlayerDemo(), 
    ); 
  } 
} 

 
class FastPixPlayerDemo extends StatefulWidget { 
  const FastPixPlayerDemo({super.key}); 
 
  @override 
  State<FastPixPlayerDemo> createState() => _FastPixPlayerDemoState(); 
} 
 
class _FastPixPlayerDemoState extends State<FastPixPlayerDemo> { 
  late FastPixPlayerController controller; 
 
  @override 
  void initState() { 
    super.initState(); 
    // Create HLS data source 
    final dataSource = FastPixPlayerDataSource.hls( 
      playbackId: 'your-playback-id-here', 
      title: 'Sample HLS Stream', 
      description: 'A sample HLS stream from FastPix', 
      thumbnailUrl: 'https://www.example.com/thumbnail.jpg', 
    ); 
 
    final configuration = FastPixPlayerConfiguration(); 
    controller = FastPixPlayerController(); 
    controller.initialize(dataSource: dataSource, configuration: configuration); 
  } 
 
  @override 
  Widget build(BuildContext context) { 
    return FastPixPlayer( 
      controller: controller, 
      width: 350, 
      height: 200, 
      aspectRatio: FastPixAspectRatio.ratio16x9, 
    ); 
  } 
 
  @override 
  void dispose() { 
    controller.dispose(); 
    super.dispose(); 
  } 
} 

Playback modes - explained in detail

FastPix supports 4 major playback modes. Each is a combination of stream type (live vs on-demand) and access (public vs private).

1. Public on-demand

Anyone with the link can watch, anytime. No login or token required.

// Create HLS data source 
final dataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  streamType: StreamType.onDemand 
); 
 
final configuration = FastPixPlayerConfiguration(); 
controller = FastPixPlayerController(); 
controller.initialize(dataSource: dataSource, configuration: configuration); 

2. Private on-demand

Private playback means the video is available anytime but only to authorized users. Access is secured using a valid JWT token, ensuring only permitted viewers can watch the content. Useful for subscriptions or internal tools.

// Create HLS data source 
final dataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  streamType: StreamType.onDemand, 
  token: "jwt-token" 
); 

3. Public live stream

Video is streamed in real-time and accessible to anyone with the link, without any authentication or token required. Great for open broadcasts.

// Create HLS data source 
final dataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  streamType: StreamType.live, 
); 

4. Private live stream

Real-time stream with token-based access control. Used for gated events or pay-per-view.

// Create HLS data source 
final dataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  streamType: StreamType.live, 
  token: "jwt-token" 
); 

PLEASE NOTE

The streamType must be explicitly set to StreamType.live or StreamType.onDemand. Leaving it blank can lead to unpredictable behavior.

Step 5: Using a custom domain

If your FastPix setup uses a custom CDN domain, you can configure it in the data source. This tells the player to construct URLs using your own domain rather than FastPix defaults.

On-demand from custom domain

// Create HLS data source 
final dataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  streamType: StreamType.onDemand, 
  customDomain: "custom-domain", 
  token: "jwt-token" 
); 

Live stream from custom domain

// Create HLS data source 
final dataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  streamType: StreamType.live, 
  customDomain: "custom-domain", 
  token: "jwt-token" 
);

PLEASE NOTE

You don’t need to specify a domain if you’re using FastPix-hosted playback. This step is optional unless you’ve customized your delivery configuration.

Step 6: Control video playback resolution

You can lock the video to a target resolution (say, 720p), or provide min/max bounds like 480p to 1080p. You can also control the order the player uses to pick renditions.

For instance, your app runs in emerging markets where users often have poor connectivity. Start at 480p and scale up only if the network supports it. This allows users to have more control over their viewing experience, reducing buffering and ensuring smooth playback.

• renditionOrder: asc means low quality → high quality.
• renditionOrder: desc does the opposite - start at the highest available.

// Quality control configuration 
final qualityControl =  FastPixPlayerQualityControl( 
  resolution:  FastPixResolution.p720, 
  minResolution:  FastPixResolution.p480, 
  maxResolution:  FastPixResolution.p1080, 
  renditionOrder:  FastPixRenditionOrder.desc, // High to low quality 
); 
 
// Create HLS data source 
final dataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  streamType: StreamType.live, 
  qualityControl: qualityControl, 
  token: "jwt-token" 
); 

PLEASE NOTE

If renditionOrder is set to asc, the player starts with the lowest resolution and scales up based on network. Use desc to prefer high-quality playback right away.

Step 7: Switch videos dynamically

Let’s say you want to play a different video after the first one finishes - or reload the player with a fresh JWT token. You don’t need to reinitialize or rebuild the player. Using updateDataSource(), you can change the playback ID, domain, or token - for example, to load a new video or refresh access credentials.

// Update data source 
final newDataSource =  FastPixPlayerDataSource.hls( 
  playbackId:  'new-playback-id', 
  customDomain:  'new-domain.com', 
  token:  'new-token', 
); 
await controller.updateDataSource(newDataSource); 

Live streaming best practices

When streaming live video, use an HLS data source with streamType: StreamType.live. It’s also important to disable caching, this ensures viewers are as close to real-time as possible and aren’t watching buffered segments.

Example: Live with cache disabled

// Create HLS data source 
final liveDataSource = FastPixPlayerDataSource.hls( 
  playbackId: 'your-playback-id-here', 
  streamType: StreamType.live, 
  cacheEnabled: false, // Cache should be disabled for live streaming 
  customDomain: "custom-domain", 
); 

PLEASE NOTE

Caching is useful for on-demand playback, but for live events, it introduces unnecessary delay. Always set cacheEnabled: false.

Error handling

Error handling in FastPix Player ensures a smooth user experience by showing a custom error UI when playback fails. You can define an errorWidgetBuilder to display meaningful messages and visuals when errors occur.

FastPixPlayer( 
  controller: controller, 
  errorWidgetBuilder: (error) { 
    return Container( 
      color: Colors.black, 
      child: Center( 
        child: Column( 
          mainAxisAlignment: MainAxisAlignment.center, 
          children: [ 
            Icon(Icons.error, color: Colors.red, size: 48), 
            SizedBox(height: 16), 
            Text( 
              'Playback Error', 
              style: TextStyle(color: Colors.white, fontSize: 18), 
            ), 
            SizedBox(height: 8), 
            Text( 
              error, 
              style: TextStyle(color: Colors.white70, fontSize: 14), 
              textAlign: TextAlign.center, 
            ), 
          ], 
        ), 
      ), 
    ); 
  }, 
); 

Parameter reference

1. FastPix player controller – Main controller class for playback management

2. FastPix player data source - Class to configure streaming source

3. FastPix player configuration – Player behavior customization

4. FastPix player quality control – Advanced quality control

5. Widgets

6. Player states

7. Display options

8. Autoplay settings

9. Supported resolutions