Livestream using FFmpeg to YouTube Live, Periscope, Facebook Live, Twitch, and many more
Python scripted livestreaming using FFmpeg
Streams to one or multiple streaming sites simultaneously, using pure object-oriented Python (no extra packages) and FFmpeg.
mypy type checking and
visual_tests.py is a quick check of several command line scripting scenarios on your laptop.
FFmpeg is used from Python
subprocess to stream to sites including:
- Facebook Live (requires FFmpeg >= 4.2 due to mandatory RTMPS)
- YouTube Live
- also Ustream, Vimeo, Restream.io and more for streaming broadcasts.
- Python scripts compute good streaming parameters, and emit the command used to copy and paste if desired.
- Works on any OS (Mac, Linux, Windows) and computing platform, including PC, Mac, and Raspberry Pi.
- Uses a pylivestream.ini file to adjust all parameters.
- does not auto-restart if network connection glitches
- is intended as a bare minimum command generator to run the FFmpeg program
- is not intended for bidirectional robust streaming--consider a program/system based on Jitsi for that.
Why not do things without the command line, via linking libffmpeg, libgstreamer or libav?
- the command-line approach does not require a compiler or OS-dependent libraries
- once you get a setup working once, you don't even need Python anymore--just copy and paste the command line
- FFmpeg ≥ 3.0 (≥ 4.2 for Facebook Live RTMPS)
- Python ≥ 3.6
Python ≥ 3.6 is required due to extensive use of type hinting to ensure program quality.
python3 -m pip install PyLivestream
git clone https://github.com/scivision/PyLivestream cd PyLivestream python3 -m pip install -e .
You can skip past this section to "stream start" if it's confusing. The defaults might work to get you started.
The pylivestream.ini file contains parameters relevant to your stream.
This file is copied into your
sys.prefix/share/pylivestream directory upon
pip install pylivestream.
We suggest copying this file to another location on your hard drive and editing, then specifying it for your streams.
[DEFAULT] section has parameters that can be overridden for each site, if desired.
screencap_origin: origin (upper left corner) of screen capture region in pixels.
screencap_res: resolution of screen capture (area to capture, starting from origin)
screencap_fps: frames/sec of screen capture
video_kbps: override automatic video bitrate in kbps
audiofs: audio sampling frequency. Typically 44100 Hz (CD quality).
audio_bps: audio data rate--leave blank if you want no audio (usually used for "file", to make an animated GIF in post-processing)
ultrafastif CPU not able to keep up.
sys.platform specific parameters.
Seek help in FFmpeg documentation, try capturing to a file first and then update
pylivestream.ini for your
- exe: override path to desired FFmpeg executable. In case you have multiple FFmpeg versions installed (say, from Anaconda Python).
Finally are the per-site parameters.
The only thing you would possibly need to change here is the
server for best performance for your geographic region.
The included pylivestream.ini is with default servers for the Northeastern USA.
Each computer will need distinct pylivestream.ini device input parameters:
- audiochan: audio device
- webcamchan: webcam device
- screenchan: desktop capture software port name
Loopback devices that let you "record what you hear" are operating system dependent. You may need to search documentation for your operating system to enable such a virtual loopback device.
ffmpeg -list_devices true -f dshow -i dummy
ffmpeg -f avfoundation -list_devices true -i ""
There are two ways to start a stream (assuming you've configured as per following sections). Both do the same thing.
- command line via Python entry_points
import pylivestream.api as plsfrom within your Python script. For more information type
The program will load a
*.key file according to the configuration file key for the website.
For example, Periscope expects to see the stream hexadecimal key in
~/periscope.key, as obtained from phone Periscope app.
Likewise, YouTube expects a file
~/youtube.key with the hexadecimal stream key and so on.
configure YouTube Live.
youtube.keyto have the YouTube hexadecimal stream key
Run Python script and chosen input will stream on YouTube Live.
Facebook Live requires FFmpeg >= 4.2 due to mandatory RTMPS
configure your Facebook Live stream
Put stream ID from https://www.facebook.com/live/create into the file
Run Python script for Facebook with chosen input
create a new stream by EITHER:
- from phone Periscope app, go to Profile -> Settings -> Periscope Producer and see your Stream Key. The "checking source" button will go to "preview stream" once you do step #2.
- from computer web browser, go to Periscope Producer and Create New Source.
Put the hexadecimal stream key into
Run Python script for Periscope with chosen input
I prefer using the Phone method as then the phone is a "second screen" where I can see if the stream is lagging, and if I "leave broadcast" and come back in, I can comment from my phone etc.
put Twitch stream key into file
Run Python script for Twitch with chosen input
Due to the complexity of streaming and the non-specific error codes FFmpeg emits, the default behavior is that if FFmpeg detects one stream has failed, ALL streams will stop streaming and the program ends.
- pylivestream.ini is setup for your computer and desired parameters
ScreenshareLivestream, more than one
sitecan be specified for simultaneous multi-streaming
- remember to setup a
*.keyfile with the hexadecimal stream key for EACH site first, OR input the stream key into the "key:" field of your
Note: your system may not have a webcam, particularly if it's a virtual machine.
webcam_res: webcam resolution -- find from
v4l2-ctl --list-formats-extor webcam spec sheet.
webcam_fps: webcam fps -- found from command above or webcam spec sheet
Stream to multiple sites, in this example Periscope and YouTube Live simultaneously:
WebcamLivestream youtube periscope
Screen Share Livestream
Stream to multiple sites, in this example Periscope and YouTube Live simultaneously:
ScreenshareLivestream youtube periscope
Image + Audio Livestream
Microphone audio + static image is accomplished by
MicrophoneLivestream youtube periscope -image doc/logo.jpg
or wherever your image file is.
Audio-only streaming is not typically allowed by the Video streaming sites. You can test it to your own computer by:
Captions: if you have installed the optional
tinytag Python module,
the Title - Artist will be added automatically onto the video from the
Loop single video endlessly
FileLoopLivestream videofile site
several video files
Glob list of video files to stream:
FileGlobLivestream path site -glob glob_pattern
-globglob pattern of files to stream e.g. "*.avi"
-loopoptionally loop endlessly the globbed file list
-shuffleoptionally shuffle the globbed file list
-imageif you have AUDIO files, you should normally set an image to display, as most/all streaming sites REQUIRE a video feed--even a static image.
-nometadisable Title - Artist text overlay
stream all videos in directory
Example: all AVI videos in directory
FileGlobLivestream ~/Videos youtube -glob "*.avi"
stream endlessly looping videos
Example: all AVI videos in
~/Videos are endlessly looped:
FileGlobLivestream ~/Videos youtube -glob "*.avi" -loop
stream all audio files in directory
Glob list of video files to stream. Suggest including a static -image (could be your logo):
FileGlobLivestream path site -glob glob_pattern -image image
pathpath to where video files are
*.avipattern matching video files
-imagefilename of image to use as stream background (REQUIRED for most websites)
Example: stream all .mp3 audio under
FileGlobLivestream ~/music youtube -glob "*.mp3" -image mylogo.jpg
Example: stream all .mp3 audio in
~/music with an animated GIF or video clip repeating:
FileGlobLivestream ~/music youtube -glob "*.mp3" -image myclip.avi
FileGlobLivestream ~/music youtube -glob "*.mp3" -image animated.gif
Screen capture to disk
This script saves your screen capture to a file on your disk:
PyLivestream.get_framerate(vidfn)gives the frames/sec of a video file.
PyLivestream.get_resolution(vidfn)gives the resolution (width x height) of video file.
- Linux requires X11, not Wayland (choose at login)
x11grabwas deprecated in FFmpeg 3.3, was previously replaced by
- Reference webpage
DirectShow didn't work for me on Windows 10, so I used gdigrab instead.
Twitch ingest servers
- Owl PC: Creative Commons no attrib. commercial
- YouTube: YouTube Brand Resources
- Facebook: Wikimedia Commons
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.