pylivestream 1.7.0

Easy streaming using FFmpeg to YouTube Live, Periscope, Facebook Live, Twitch, ...

Python scripted livestreaming using FFmpeg

Streams to one or multiple streaming sites simultaneously, using pure object-oriented Python (no extra packages) and FFmpeg. Tested with flake8, mypy type checking and pytest. FFmpeg is used from Python subprocess to stream to Facebook Live, YouTube Live, Periscope, Twitch, Mixer, Ustream, Vimeo and more for streaming broadcasts.

• Python scripts compute good streaming parameters, and emit the command used so you can just copy and paste in the future if you wish.

• Works on any OS (Mac, Linux, Windows) and computing platform, including PC, Mac, and Raspberry Pi.

• Uses an .ini file to adjust all parameters.

FFmpeg:

>= 3.0 required

Python:

>= 3.6 required

Contents

• Python scripted livestreaming using FFmpeg

  • Install

  • Configuration

  • Stream Start

    • YouTube Live

    • Facebook Live

    • Periscope

    • Twitch

  • Usage

    • Webcam

    • Screen Share Livestream

    • File Input

      • Loop single video endlessly

      • several video files

      • stream all videos in directory

      • stream endlessly looping videos

      • stream all audio files in directory

    • Screen capture to disk

  • Utilities

  • Notes

    • FFmpeg References

      • Windows

    • Stream References

    • Logo Credits

Install

Latest release:

python -m pip install PyLivestream

Development version:

git clone https://github.com/scivision/PyLivestream

cd PyLivestream

python -m pip install -e .

Configuration

You can skip past this section to “stream start” if it’s confusing. The defaults might work to get you started.

The stream.ini file contains parameters relevant to your stream. The [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

• 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)

• preset: veryfast or ultrafast if CPU not able to keep up.

Next are sys.platform specific parameters.

Seek help in FFmpeg documentation, try capturing to a file first and then update stream.ini for your sys.platform.

• 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 stream.ini is with default servers for the Northeastern USA.

Stream Start

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 the app. Likewise, YouTube expects a file youtube.key with the hexadecimal stream key and so on.

YouTube Live

1. configure YouTube Live.

2. Edit file youtube.key to have the YouTube hexadecimal stream key

3. Run Python script and chosen input will stream on YouTube Live.

python ScreenshareLivestream.py youtube

Facebook Live

1. configure your Facebook Live stream

2. Put stream ID from https://www.facebook.com/live/create into the file facebook.key

3. Run Python script for Facebook with chosen input

python ScreenshareLivestream.py facebook

Periscope

1. 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 https://www.periscope.tv/account/producer and Create New Source.

2. Put the hexadecimal stream key into periscope.key

3. Run Python script for Periscope with chosen input

python ScreenshareLivestream.py periscope

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.

Twitch

1. create stream from Twitch Dashboard. If you are not in the Northeast US, edit stream.ini to have the closest server.

2. put Twitch stream key into file twitch.key

3. Run Python script for Twitch with chosen input

python ScreenshareLivestream.py twitch

Usage

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.

• stream.ini is setup for your computer and desired parameters

• site is facebook, periscope, youtube, etc.

• For Webcam.py and Screenshare.py, more than one site can be specified for simultaneous multi-streaming

• remember to setup a *.key file with the hexadecimal stream key for EACH site first, OR input the stream key into the “key:” field of your *.ini file.

Webcam

Note: your system may not have a webcam, particularly if it’s a virtual machine.

Config:

• webcam_res: webcam resolution – find from v4l2-ctl --list-formats-ext or webcam spec sheet.

• webcam_fps: webcam fps – found from command above or webcam spec sheet

Find webcam name by:

• Windows: ffmpeg -list_devices true -f dshow -i dummy

• Mac: ffmpeg -f avfoundation -list_devices true -i ""

• Linux: v4l2-ctl --list-devices

---

Audio is included:

python WebcamLivestream.py site(s)

Stream to multiple sites, in this example Periscope and YouTube Live simultaneously:

python WebcamLivestream.py youtube periscope

Screen Share Livestream

Audio is included:

python ScreenshareLivestream.py site(s)

Stream to multiple sites, in this example Periscope and YouTube Live simultaneously:

python ScreenshareLivestream.py youtube periscope

File Input

Captions: if you have installed the optional tinytag Python module, the Title - Artist will be added automatically onto the video from the audio/video files.

Loop single video endlessly

python FileLoopLivestream.py site videofile

several video files

Glob list of video files to stream:

python FileGlobLivestream.py path site -glob glob_pattern

-glob

glob pattern of files to stream e.g. “*.avi”

-loop

optionally loop endlessly the globbed file list

-shuffle

optionally shuffle the globbed file list

-image

if 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.

-nometa

disable Title - Artist text overlay

stream all videos in directory

Example: all AVI videos in directory ~/Videos:

python FileGlobLivestream.py ~/Videos youtube -glob "*.avi"

stream endlessly looping videos

Example: all AVI videos in ~/Videos are endlessly looped:

python FileGlobLivestream.py ~/Videos youtube -glob "*.avi" -loop

stream all audio files in directory

Glob list of video files to stream. Must include a static image (could be your logo):

python FileGlobLivestream.py path site -glob glob_pattern -image image

path path to where video files are pattern e.g. *.avi pattern matching video files -image filename of image to use as stream background (REQUIRED for most websites)

Example: stream all .mp3 audio under ~/Library directory:

python FileGlobLivestream.py ~/Library youtube -glob "*.mp3" -image mylogo.jpg

Screen capture to disk

This script saves your screen capture to a file on your disk:

python ScreenCapture2disk.py myvid.avi

Utilities

• 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.

Notes

• Linux requires X11, not Wayland (choose at login)

• x11grab was deprecated in FFmpeg 3.3, was previously replaced by xcbgrab

• Reference webpage

• Test videos for looping/globbing

Comments on dropouts / lag for livestreaming in general (not just with this program):

• Low CPU machines (like Raspberry Pi) may need to cut back on resolution.

• live streaming takes an excellent quality (not necessarily high speed) Internet connection in general. Some DSL / wireless internet provider have really spotty performance. You might not notice this with HD Netflix due to deep buffering, but it will show up on livestreaming.

• Do Skype / Duo / FaceTime work excellently for you on your network? If not, live streaming will not work well.

• Try a wired (Ethernet) connection to the Internet. I have seen very expensive consumer WiFi APs that just had bad performance in real world strenuous use (like live streaming).

FFmpeg References

• streaming

• webcam

• webcam overlay

Windows

• gdigrab

DirectShow didn’t work for me on Windows 10, so I used gdigrab instead.

• DirectShow device selection

• DirectShow examples

Stream References

• Twitch parameters

• Twitch servers

• Periscope parameters

• YouTube Live parameters

• Facebook Live parameters

• Mixer parameters

• Mixer server list

• Ustream parameters

• Vimeo config

• Vimeo parameters

Logo Credits

• Owl PC: Creative Commons no attrib. commercial

• YouTube: YouTube Brand Resources

• Facebook: Wikimedia Commons

• Periscope