From c1807682a1f31924e3eb5ddc8028b2afa1b0331b Mon Sep 17 00:00:00 2001 From: "Michael Hirsch, Ph.D" Date: Thu, 30 May 2019 16:40:30 -0400 Subject: [PATCH] doc [skip ci] doc [skip ci] --- README.md | 114 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 59 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index ebff6d7..88ecb9a 100644 --- a/README.md +++ b/README.md @@ -7,14 +7,14 @@ # 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`. +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`. `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 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 to copy and paste if desired. * Works on any OS (Mac, Linux, Windows) and computing platform, including PC, Mac, and Raspberry Pi. -* Uses an `.ini` file to adjust all parameters. +* Uses a [pylivestream.ini](./pylivestream/pylivestream.ini) file to adjust all parameters. However, note that PyLivestream: @@ -31,7 +31,9 @@ However, note that PyLivestream: Requirements: * FFmpeg ≥ 3.0 -* Python ≥ 3.6 +* Python ≥ 3.6 + +Python ≥ 3.6 is required due to extensive use of type hinting to ensure program quality. Latest release: @@ -46,34 +48,35 @@ Development version: python -m pip install -e . -## Configuration +## Configuration: pylivestream.ini -You can skip past this section to "stream start" if it's confusing. +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 [pylivestream.ini](./pylivestream/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. + 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) +- `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`. +then update [pylivestream.ini](./pylivestream/pylivestream.ini) for your `sys.platform`. -- `exe`: override path to desired FFmpeg executable. In case you have - multiple FFmpeg versions installed (say, from Anaconda Python). +* 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. +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](./pylivestream/pylivestream.ini) is with default servers for the Northeastern USA. ## Stream Start @@ -107,7 +110,7 @@ so on. 1. create a new stream by EITHER: - * from phone Periscope app, go to Profile -> Settings -> Periscope Producer and see your Stream Key. + * 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) @@ -124,9 +127,7 @@ come back in, I can comment from my phone etc. ### Twitch -1. create stream from [Twitch - Dashboard](http://www.twitch.tv/broadcast/dashboard). If you are not - in the Northeast US, edit `stream.ini` to have the [closest server](http://bashtech.net/twitch/ingest.php). +1. create stream from [Twitch Dashboard](http://www.twitch.tv/broadcast/dashboard). If you are not in the Northeast US, edit [pylivestream.ini](./pylivestream/pylivestream.ini) to have the [closest server](http://bashtech.net/twitch/ingest.php). 2. put Twitch stream key into file `twitch.key` 3. Run Python script for Twitch with chosen input @@ -136,35 +137,39 @@ come back in, I can comment from my phone etc. ## 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. +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 `WebcamLivestream` and `ScreenshareLivestream`, 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. +* [pylivestream.ini](./pylivestream/pylivestream.ini) is setup for your computer and desired parameters +* `site` is `facebook`, `periscope`, `youtube`, etc. +* For `WebcamLivestream` and `ScreenshareLivestream`, 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. +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 +- `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` +* Windows: + + ```sh + ffmpeg -list_devices true -f dshow -i dummy + ``` +* MacOS: + + ```sh + ffmpeg -f avfoundation -list_devices true -i "" + +* Linux: + + ```sh + v4l2-ctl --list-devices + ``` Audio is included: @@ -203,10 +208,10 @@ Glob list of video files to stream: FileGlobLivestream 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. +* `-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 @@ -218,20 +223,21 @@ Example: all AVI videos in directory `~/Videos`: #### stream endlessly looping videos Example: all AVI videos in `~/Videos` are endlessly looped: + ```sh FileGlobLivestream ~/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): +Glob list of video files to stream. Suggest including a static -image (could be your logo): + ```sh FileGlobLivestream path site -glob glob_pattern -image image ``` -* `path` path to where video files are -* `glob_pattern` e.g. `*.avi` pattern matching video files +* `path` path to where video files are +* `glob_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 `~/music` directory: @@ -246,7 +252,7 @@ FileGlobLivestream ~/music youtube -glob "*.mp3" -image myclip.avi or ```sh FileGlobLivestream ~/music youtube -glob "*.mp3" -image animated.gif -``` +``` ### Screen capture to disk @@ -276,16 +282,16 @@ Comments on dropouts / lag for livestreaming in general (not just with this prog 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. +- Try a wired (Ethernet) connection to the Internet. I have seen very expensive consumer WiFi APs that had bad performance in real world strenuous use (like live streaming). ### Troubleshooting -Black / Blank desktop sharing video. +Black / Blank desktop sharing video. In general since this program generates command lines that are run by FFmpeg, try just using FFmpeg by itself to write to a video file. This is a known issue with Wayland--instead use X11. See [FFmpeg Desktop capture docs](https://trac.ffmpeg.org/wiki/Capture/Desktop). - + ### YouTube stream health Particularly when streaming with a static background `-image`, YouTube will often warn in "Stream Health": @@ -306,10 +312,8 @@ Disregard this warning as long as your image looks OK. DirectShow didn't work for me on Windows 10, so I used gdigrab instead. -- [DirectShow](https://trac.ffmpeg.org/wiki/DirectShow) device - selection -- DirectShow - [examples](https://ffmpeg.org/ffmpeg-devices.html#Examples-4) +- [DirectShow](https://trac.ffmpeg.org/wiki/DirectShow) device selection +- DirectShow [examples](https://ffmpeg.org/ffmpeg-devices.html#Examples-4) ### Stream References