python-ffmpeg-video-streaming 0.1.0

Package media content for online streaming(DASH and HLS) using ffmpeg

📼 Python FFmpeg Video Streaming

Overview

This package uses the FFmpeg to package media content for online streaming such as DASH and HLS. You can also use DRM for HLS packaging. There are several options to open a file from a cloud and save files to clouds as well.

• Full Documentation is available describing all features and components.
• As of version 0.1.0, almost all files have been renewed, see the documentation for more information. If you find any bugs in the library, please file an issue. Pull requests are also welcome.

Contents

• Requirements
• Installation
• Quickstart
  • Opening a Resource
  • DASH
  • HLS
    • Encryption(DRM)
  • Transcoding
  • Saving Files
  • Metadata
  • Conversion
• Several Open Source Players
• Contributing and Reporting Bugs
• Credits
• License

Requirements

1. This version of the package is only compatible with Python 3.6 or higher.

2. To use this package, you need to install the FFmpeg. You will need both FFmpeg and FFProbe binaries to use it.

Installation

Install the package via pip:

pip install python-ffmpeg-video-streaming

Alternatively, add the dependency directly to your requirements.txt file:

python-ffmpeg-video-streaming==0.1.0

Quickstart

First of all, you need to import the package in your code:

import ffmpeg_streaming

Opening a Resource

There are several ways to open a resource.

1. From a FFmpeg supported resource

You can pass a local path of video(or a supported resource) to the open method:

video = ffmpeg_streaming.input('/var/media/video.mp4')

See FFmpeg Protocols Documentation for more information about supported resources such as http, ftp, and etc.

For example:

video = ffmpeg_streaming.input('https://www.aminyazdanpanah.com/?"PATH TO A VIDEO FILE" or "PATH TO A LIVE HTTP STREAM"')

2. From Clouds

You can open a file from a cloud by passing an array of cloud configuration to the openFromCloud method.

from ffmpeg_streaming import S3
s3 = S3(aws_access_key_id='YOUR_KEY_ID', aws_secret_access_key='YOUR_KEY_SECRET', region_name='YOUR_REGION')

video = ffmpeg_streaming.input(s3, bucket_name="bucket-name", key="video.mp4")

Visit this page to see some examples of opening a file from Amazon S3, Google Cloud Storage, Microsoft Azure Storage, and a custom cloud.

3. Capture Webcam or Screen (Live Streaming)

You can pass a name of the supported, connected capture device(i.e. name of webcam, camera, screen and etc) to the capture method to stream a live media over network.

video = ffmpeg_streaming.input('CAMERA NAME OR SCREEN NAME', capture=True)

To list the supported, connected capture devices, see FFmpeg Capture Webcam and FFmpeg Capture Desktop.

DASH

Dynamic Adaptive Streaming over HTTP (DASH), also known as MPEG-DASH, is an adaptive bitrate streaming technique that enables high quality streaming of media content over the Internet delivered from conventional HTTP web servers. Learn more

Create DASH files:

from ffmpeg_streaming import Formats

dash = video.dash(Formats.hevc())
dash.auto_generate_representations()
dash.output('/var/media/dash.mpd')

Generate representations manually:

from ffmpeg_streaming import Formats, Bitrate, Representation, Size

_144p  = Representation(Size(256, 144), Bitrate(95 * 1024, 64 * 1024))
_240p  = Representation(Size(426, 240), Bitrate(150 * 1024, 94 * 1024))
_360p  = Representation(Size(640, 360), Bitrate(276 * 1024, 128 * 1024))
_480p  = Representation(Size(854, 480), Bitrate(750 * 1024, 192 * 1024))
_720p  = Representation(Size(1280, 720), Bitrate(2048 * 1024, 320 * 1024))
_1080p = Representation(Size(1920, 1080), Bitrate(4096 * 1024, 320 * 1024))
_2k    = Representation(Size(2560, 1440), Bitrate(6144 * 1024, 320 * 1024))
_4k    = Representation(Size(3840, 2160), Bitrate(17408 * 1024, 320 * 1024))

dash = video.dash(Formats.hevc())
dash.representations(_144p, _240p, _360p, _480p, _720p, _1080p, _2k, _4k)
dash.output('/var/media/dash.mpd')

See DASH section in the documentation, for more examples.

HLS

HTTP Live Streaming (also known as HLS) is an HTTP-based adaptive bitrate streaming communications protocol implemented by Apple Inc. as part of its QuickTime, Safari, OS X, and iOS software. Client implementations are also available in Microsoft Edge, Firefox and some versions of Google Chrome. Support is widespread in streaming media servers. Learn more

Create HLS files:

from ffmpeg_streaming import Formats

hls = video.hls(Formats.h264())
hls.auto_generate_representations()
hls.output('/var/media/hls.m3u8')

Generate representations manually:

from ffmpeg_streaming import Formats, Bitrate, Representation, Size

_360p  = Representation(Size(640, 360), Bitrate(276 * 1024, 128 * 1024))
_480p  = Representation(Size(854, 480), Bitrate(750 * 1024, 192 * 1024))
_720p  = Representation(Size(1280, 720), Bitrate(2048 * 1024, 320 * 1024))

hls = video.hls(Formats.hevc())
hls.representations(_360p, _480p, _720p)
hls.output('/var/media/hls.m3u8')

See HLS section in the documentation, for more examples such as Fragmented MP4, live from camera/screen and so on.

Encryption(DRM)

The encryption process requires some kind of secret (key) together with an encryption algorithm. HLS uses AES in cipher block chaining (CBC) mode. This means each block is encrypted using the ciphertext of the preceding block. Learn more

You must specify a path to save a random key to your local machine and also a URL(or a path) to access the key on your website(the key you will save must be accessible from your website). You must pass both these parameters to the encryption method:

Single Key

The following code generates a key for all segment files.

#A path you want to save a random key to your server
save_to = '/home/public_html/"PATH TO THE KEY DIRECTORY"/key'

#A URL (or a path) to access the key on your website
url = 'https://www.aminyazdanpanah.com/?"PATH TO THE KEY DIRECTORY"/key'
# or url = '/PATH TO THE KEY DIRECTORY/key';

from ffmpeg_streaming import Formats

hls = video.hls(Formats.h264())
hls.encryption(save_to, url)
hls.auto_generate_representations()
hls.output('/var/media/hls.m3u8')

Key Rotation

An integer as a "key rotation period" can also be passed to the encryption method (i.e. encryption(save_to, url, 10)) to use a different key for each set of segments, rotating to a new key after this many segments. For example, if 10 segment files have been generated then it will generate a new key. If you set this value to 1, each segment file will be encrypted with a new encryption key. This can improve security and allows for more flexibility.

See the example for more information.

IMPORTANT: It is very important to protect your key(s) on your website. For example, you can check a token(using a Get or Post HTTP method) to access the key(s) on your website. You can also check a session(or cookie) on your website to restrict access to the key(s)(It is highly recommended).

DRM

However FFmpeg supports AES encryption for HLS packaging, which you can encrypt your content, it is not a full DRM solution. If you want to use a full DRM solution, I recommend trying FairPlay Streaming solution which then securely exchange keys, and protect playback on devices.

Apple’s FairPlay is a recommended DRM system, but you can use other DRM systems such as Microsoft's PlayReady and Google’s Widevine.

Transcoding

You can get realtime information about the transcoding using the following code.

from ffmpeg_streaming import Formats
import sys

def monitor(ffmpeg, duration, time_):
    per = round(time_ / duration * 100)
    sys.stdout.write("\rTranscoding...(%s%%) [%s%s]" % (per, '#' * per, '-' * (100 - per)))
    sys.stdout.flush()

hls = video.hls(Formats.h264())
hls.auto_generate_representations()
hls.output('/var/media/hls.m3u8')

Output From a Terminal:

Saving Files

There are several ways to save files.

1. To a Local Path

You can pass a local path to the output method. If there was no directory in the path, then the package auto makes the directory.

from ffmpeg_streaming import Formats

dash = video.dash(Formats.hevc())
dash.auto_generate_representations()

dash.output('/var/media/dash.mpd')

It can also be null. The default path to save files is the input path.

from ffmpeg_streaming import Formats

hls = video.hls(Formats.h264())
hls.auto_generate_representations()

hls.output()

NOTE: If you open a file from a cloud and do not pass a path to save the file to your local machine, you will have to pass a local path to the save method.

2. To Clouds

You can save your files to a cloud by passing an array of cloud configuration to the save method.

from ffmpeg_streaming import  S3, CloudManager

s3_cloud = S3(aws_access_key_id='YOUR_KEY_ID', aws_secret_access_key='YOUR_KEY_SECRET', region_name='YOUR_REGION')
s3 = CloudManager().add(s3_cloud, bucket_name="bucket-name")

hls.output(clouds=s3)

A path can also be passed to save a copy of files to your local machine.

hls.output('/var/media/hls.m3u8', clouds=s3)

Visit this page to see some examples of saving files to Amazon S3, Google Cloud Storage, Microsoft Azure Storage, and a custom cloud.

NOTE: This option(Save To Clouds) is only valid for VOD (it does not support live streaming).

Schema: The relation is one-to-many

3. To a Server Instantly

You can pass a url(or a supported resource like ftp) to live method to upload all the segments files to the HTTP server(or other protocols) using the HTTP PUT method, and update the manifest files every refresh times.

If you want to save stream files to your local machine, use the save method.

# DASH
dash.output('http://YOUR-WEBSITE.COM/live-stream/out.mpd')

# HLS
hls.output('http://YOUR-WEBSITE.COM/live-stream/out.m3u8')

NOTE: In the HLS format, you must upload the master playlist to the server manually. (Upload the /var/www/stream/live-master-manifest.m3u8 file to the http://YOUR-WEBSITE.COM)

See FFmpeg Protocols Documentation for more information.

Metadata

You can get information from multimedia streams and the video file using the following code.

from ffmpeg_streaming import FFProbe

ffprobe = FFProbe('/var/media/video.mp4')

See the example for more information.

Conversion

You can convert your stream to a file or to another stream protocols. You should pass a manifest of the stream to the open method:

1. HLS To DASH

from ffmpeg_streaming import Formats, Bitrate, Representation, Size

video = ffmpeg_streaming.input('https://www.aminyazdanpanah.com/?PATH/TO/HLS-MANIFEST.M3U8')

_480p  = Representation(Size(854, 480), Bitrate(750 * 1024, 192 * 1024))

dash = video.dash(Formats.hevc())
dash.representations(_480p)
dash.output('/var/media/dash.mpd')

2. DASH To HLS

video = ffmpeg_streaming.input('https://www.aminyazdanpanah.com/?PATH/TO/DASH-MANIFEST.MPD')

hls = video.hls(Formats.h264())
hls.auto_generate_representations()
hls.output('/var/media/hls.m3u8')

3. Stream(DASH or HLS) To File

video = ffmpeg_streaming.input('https://www.aminyazdanpanah.com/?PATH/TO/MANIFEST.MPD or M3U8')

stream = video.stream2file(Formats.h264())
stream.output('/var/media/new-video.mp4')

Several Open Source Players

You can use these libraries to play your streams.

• WEB
  • DASH and HLS:
    • Video.js 7 (Recommended) - videojs-http-streaming (VHS)
    • Plyr
    • DPlayer
    • MediaElement.js
    • Clappr
    • Shaka Player
    • Flowplayer
  • DASH:
    • dash.js
  • HLS:
    • hls.js
• Android
  • DASH and HLS:
    • ExoPlayer
• IOS
  • DASH:
    • MPEGDASH-iOS-Player
  • HLS:
    • Player
• Windows, Linux, and macOS
  • DASH and HLS:
    • FFmpeg(ffplay)
    • VLC media player

NOTE-1: You must pass a link of the master playlist(manifest)(i.e. https://www.aminyazdanpanah.com/?"PATH TO STREAM DIRECTORY"/dash-stream.mpd or /PATH_TO_STREAM_DIRECTORY/hls-stream.m3u8 ) to these players.

NOTE-2: If you save your stream to a cloud(i.e. Amazon S3), the link of your playlist and also other content MUST BE PUBLIC.

NOTE-3: As you may know, IOS does not have native support for DASH. Although there are some libraries such as Viblast and MPEGDASH-iOS-Player to support this technique, I have never tested them. So maybe som of them will not work correctly.

Contributing and Reporting Bugs

I'd love your help in improving, correcting, adding to the specification. Please file an issue or submit a pull request.

• Please see Contributing File for more information.
• If you have any questions or you want to report a bug, please just file an issue
• If you discover a security vulnerability within this package, please see SECURITY File for more information.

NOTE: If you have any questions about this package or FFmpeg, DO NOT send an email to me (or DO NOT submit the contact form on my website). Emails regarding these issues will be ignored.

Credits

• Amin Yazdanpanah
• All Contributors

License

The MIT License (MIT). See License File for more information.