Skip to content
šŸ“¼ Package media content for online streaming(DASH and HLS) using FFmpeg
Python
Branch: master
Clone or download
Latest commit 9fa6c94 Dec 26, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github undone Dec 26, 2019
examples remove cloud dependencies Dec 26, 2019
ffmpeg_streaming update test Dec 26, 2019
.appveyor.yml remove cloud dependencies Dec 26, 2019
.gitignore objects Mar 23, 2019
.travis.yml remove cloud dependencies Dec 26, 2019
CODE_OF_CONDUCT.md bug fixes and performance enhancements Apr 7, 2019
CONTRIBUTING.md bug fixes and performance enhancements Apr 7, 2019
LICENSE
Pipfile remove cloud dependencies Dec 26, 2019
README.md remove cloud dependencies Dec 26, 2019
SECURITY.md
_config.yml
renovate.json
requirements.txt remove cloud dependencies Dec 26, 2019

README.md

šŸ“¼ Python FFmpeg Video Streaming

Build Status Build status Downloads PyPI version Software License

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 clouds and save files to them as well.

Contents

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

The latest version of ffmpeg-streaming can be acquired via pip:

pip install python-ffmpeg-video-streaming

Quickstart

opening a file

There are two ways to open a file:

1. From a Local Path

video = '/var/www/media/videos/video.mp4'

2. From Clouds

You can open a file from a cloud by passing a tuple of cloud configuration to the method.

In this page, you will find some examples of opening a file from Amazon S3, Google Cloud Storage, Microsoft Azure Storage, and a custom cloud.

video = (google_cloud, download_options, None)

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:

import ffmpeg_streaming

(
    ffmpeg_streaming
        .dash(video, adaption='"id=0,streams=v id=1,streams=a"')
        .format('libx265')
        .auto_rep()
        .package('/var/www/media/videos/dash/dash-stream.mpd')
)

Generate representations manually:

import ffmpeg_streaming
from ffmpeg_streaming import Representation

r_144p  = Representation(width=256, height=144, kilo_bitrate=95)
r_240p  = Representation(width=426, height=240, kilo_bitrate=150)
r_360p  = Representation(width=640, height=360, kilo_bitrate=276)
r_480p  = Representation(width=854, height=480, kilo_bitrate=750)
r_720p  = Representation(width=1280, height=720, kilo_bitrate=2048)
r_1080p = Representation(width=1920, height=1080, kilo_bitrate=4096)
r_2k    = Representation(width=2560, height=1440, kilo_bitrate=6144)
r_4k    = Representation(width=3840, height=2160, kilo_bitrate=17408)

(
    ffmpeg_streaming
        .dash(video, adaption='"id=0,streams=v id=1,streams=a"')
        .format('libx265')
        .add_rep(r_144p, r_240p, r_360p, r_480p, r_720p, r_1080p, r_2k, r_4k)
        .package('/var/www/media/videos/dash/dash-stream.mpd')
)

See DASH examples and DASH options for more information.

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:

import ffmpeg_streaming

(
    ffmpeg_streaming
        .hls(video, hls_time=10, hls_allow_cache=1)
        .format('libx264')
        .auto_rep()
        .package('/var/www/media/videos/hls/hls-stream.m3u8')
)

Generate representations manually:

import ffmpeg_streaming
from ffmpeg_streaming import Representation

r_360p = Representation(width=640, height=360, kilo_bitrate=276)
r_480p = Representation(width=854, height=480, kilo_bitrate=750)
r_720p = Representation(width=1280, height=720, kilo_bitrate=2048)

(
    ffmpeg_streaming
        .hls(video, hls_time=10, hls_allow_cache=1)
        .format('libx264')
        .add_rep(r_360p, r_480p, r_720p)
        .package('/var/www/media/videos/hls/hls-stream.m3u8')
)

NOTE: You cannot use HEVC(libx265) and VP9 formats for HLS packaging.

Encrypted HLS

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:

import ffmpeg_streaming

#A path you want to save a random key to your server
save_to = '/home/public_html/PATH_TO_KEY_DIRECTORY/random_key.key'

#A URL (or a path) to access the key on your website
url = 'https://www.aminyazdanpanah.com/PATH_TO_KEY_DIRECTORY/random_key.key'
# or url = '/PATH_TO_KEY_DIRECTORY/random_key.key'

(
    ffmpeg_streaming
        .hls(video, hls_time=10, hls_allow_cache=1)
        .encryption(url, save_to)
        .format('libx264')
        .auto_rep(heights=[480, 360, 240])
        .package('/var/www/media/videos/hls/hls-stream.m3u8')
)

NOTE: It is very important to protect your key on your website using a token or a session/cookie(It is highly recommended).

See HLS examples and HLS options for more information.

Progress

You can get realtime information about transcoding by passing a callable method to the package method:

import sys
import time
import logging

import ffmpeg_streaming


start_time = time.time()
logging.basicConfig(filename='Transcoding-' + str(start_time) + '.log', level=logging.DEBUG)

def progress(percentage, ffmpeg):
    # You can update a field in your database
    # You can also create a socket connection and show a progress bar to users
    logging.debug(ffmpeg)
    sys.stdout.write("\rTranscoding...(%s%%)[%s%s]" % (percentage, '#' * percentage, '-' * (100 - percentage)))
    sys.stdout.flush()


(
    ffmpeg_streaming
        .hls(video)
        .format('libx264')
        .auto_rep()
        .package('/var/www/media/videos/hls/hls-stream.m3u8', progress=progress)
)

Output from a terminal: transcoding

Saving Files

There are two ways to save your files.

1. To a Local Path

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

(
    ffmpeg_streaming
        .hls(video)
        .format('libx264')
        .auto_rep()
        .package('/var/www/media/videos/hls/hls-stream.m3u8', progress=progress)
)

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

(
    ffmpeg_streaming
        .hls(video)
        .format('libx264')
        .auto_rep()
        .package(progress=progress)
)

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 package method.

2. To Clouds

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

In this page, you will find some examples of saving files to Amazon S3, Google Cloud Storage, Microsoft Azure Storage, and a custom cloud.

(
    ffmpeg_streaming
        .dash('/var/www/media/video.mkv', adaption='"id=0,streams=v id=1,streams=a"')
        .format('libx265')
        .auto_rep()
        .package(clouds=[to_aws_cloud, to_azure_cloud, to_google_cloud],
                 progress=progress)
)

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

(
    ffmpeg_streaming
        .dash('/var/www/media/video.mkv', adaption='"id=0,streams=v id=1,streams=a"')
        .format('libx265')
        .auto_rep()
        .package(output='/var/www/media/stream.mpd', clouds=[to_aws_cloud, to_google_cloud],
                 progress=progress)
)

Schema: The relation is one-to-many.

Probe

You can extract the metadata of the video file using the following code:

from ffmpeg_streaming import FFProbe

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

NOTE: You can save these metadata to your database.

See the example for more information.

Several Open Source Players

You can use these libraries to play your streams.

NOTE: You should pass a manifest of stream(e.g. https://www.aminyazdanpanah.com/PATH_TO_STREAM_DIRECTORY/dash-stream.mpd or /PATH_TO_STREAM_DIRECTORY/hls-stream.m3u8 ) to these players.

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, please DO NOT send an email to me (or submit the contact form on my website). Emails regarding these issues will be ignored.

Credits

License

The MIT License (MIT). Please see License File for more information.

You canā€™t perform that action at this time.