1. Most of the help text is outdated (e.g. --noisy is required for it to print to the console at all)
2. Most of the instructions below are also outdated. (Usage and Installation still work but they are missing a lot of information.)
3. pyyaml is not in requirements.txt (needed for config files)
4. config file format is not fixed

Basic usage remains the same as previous versions, except that --all is once again not the default mode. To run the script and download all streaming rooms to the data directory (by default ~/Downloads/Showroom) enter:

python showroom.py --all

(Using the showroom virtual environment if it was configured.)

To download only specific members' rooms, use:

python showroom.py "Member Name" ["Another Member Name" ...]

To set a different data directory, use:

python showroom.py --data-dir <data directory> [--all or "Member Name"]

For additional options, type:

python showroom.py --help

Or take a gander at the start.sh script.

Requires FFmpeg, Python 3.5+, and the Python libraries requests, websocket-client, and pyyaml

Either download prebuilt binaries from the FFmpeg website or your distro's package manager, or compile it from source. If you do choose to compile it yourself (unnecessary for this script) you must use the --enable-librtmp build flag. It is also highly recommended to use --enable-openssl in addition to the codecs suggested in the FFmpeg compilation guide. Each requires the relevant system libraries (librtmp, openssl, etc.) to be installed before building.

Libav will not be supported.

Currently this script does not respect user defined executable paths (e.g. ~/.local/bin) so only ffmpeg executables located in the system path will be used. This will change in the future, and an option to specify the location of ffmpeg will be added.

Download and install from the Python website or your distro's package manager. Python 3.6.x is strongly recommended, both because future versions of the script may make use of the new features added in 3.6, and for speed improvements.

Using a virtual environment rather than installing packages into your system environment is also strongly recommended. The recommended tool for this is virtualenvwrapper, although many other alternatives exist. Follow the Installation Guide through to the Quick-Start section, then set up a virtual environment for Showroom using:

mkvirtualenv showroom --python=python3

It will be automatically activated after creation, but to activate it again in the future, use:

workon showroom

and deactivate with:

deactivate

All calls to pip beyond this point should be made with the virtual environment active.

Clone the repository using git:

git clone https://github.com/wlerin/showroom.git

Or use the Download as ZIP button above.

All required packages can be installed by running:

pip install -r requirements.txt

in the showroom directory.

• BeautifulSoup

Used by by index_maker to generate new Room entries. (index_maker is not yet included in this repository)

pip install beautifulsoup4

• lxml

Fast XML parser used by BeautifulSoup (but not required for it). Needs the libxml2 and libxslt C libraries installed.

pip install lxml

Showroom can read its configuration from a file, by default called "showroom.conf", located in one of the following locations:

Mac OS X:     ~/Library/Application Support/Showroom/
Unix:         ~/.config/Showroom/
Win 7+:       C:\Users\<username>\AppData\Local\Showroom\

Technically you can then define a different config directory, but this does nothing. You can also start the script with the --config option to manually specify a config file. The config file must be formatted in either JSON or, if PyYAML was installed, YAML.

Sample YAML Config File:

directory:
    data: null  # ~/Downloads/Showroom
    output: "{data}"
    index: index
    log: null
    config: null
    temp: "{data}/active"
file:
    config: "{directory.config}/showroom.conf"
    schedule: "{directory.data}/schedule.json"
    completed: "{directory.data}/completed.json"
throttle:
    max:
        downloads: 80
        watches:   50
        priority:  80
    rate:
        upcoming: 180.0
        onlives:    7.0
        watch:      2.0
        live:      60.0
    timeout:
        download:  23.0
ffmpeg:
    logging: false
filter:
    all: false
    wanted: []
    unwanted: []
feedback:
    console: false
    write_schedules_to_file: true

All fields are optional and will be filled in with default values if omitted or set to null. (In fact, the values given here are default values, except where the defaults require further processing.) If necessary, other fields can be referenced using "{key[.subkey]}" syntax, but be careful to avoid recursive references. I.e. don't set config to "{data}" and data to "{config}". References will be resolved either "locally" (e.g. "{data}") or from the outermost scope (e.g. "{directory.data}"). Using these references for non-string values is not yet supported.

TODO: description of config fields

Several new data files are now stored in the data directory.

The script now tracks all scheduled and live rooms (whether or not they are being downloaded) and prints information about them to a file called "schedule.json", where they can be read by other programs. The file contains a JSON array, where each item is a JSON object containing the following fields:

{
   "name": "Member Name",
   "live": true | false,
   "status": "scheduled" | "watching" | "live" | "downloading",
   "start_time": "YYYY-MM-DD HH:mm:ss",
   "streaming_urls": { "hls_url": "http(s)://...",
                      "rtmp_url": "rtmp://..."},
   "room": {...} # same as the room data stored in index files
}

More fields may be added in the future.

TODO

TODO

TODO