Skip to content

Commit

Permalink
doc [skip ci]
Browse files Browse the repository at this point in the history 
doc [skip ci]
  • Loading branch information
@scivision
scivision committed May 30, 2019
1 parent 6911cee commit c180768
Showing 1 changed file with 59 additions and 55 deletions.
114 changes: 59 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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:
Expand All @@ -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

Expand Down Expand Up @@ -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>](https://www.periscope.tv/account/producer)
Expand All @@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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

Expand Down Expand Up @@ -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":
Expand All @@ -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

Expand Down

0 comments on commit c180768

Please sign in to comment.