1 Getting Started

1.1 Installation

Install Overscan following the instructions at raco pkg install:

  raco pkg install git://github.com:mwunsch/overscan

Overscan requires the GStreamer and GObject Introspection libraries to be installed, along with a number of GStreamer plugins. Several of these plugins are platform-specific e.g. plugins for accessing camera and audio sources. Overscan, still in its infancy, is currently only configured to work on a Mac. Overscan has been tested on macOS Sierra and Racket v6.12. The requirements are assumed to be installed via Homebrew.

  brew install gstreamer

This will install the core GStreamer framework, along with GObject Introspection libraries as a dependency. Overscan has been tested with GStreamer version 1.14.0.

From here, you have to install the different GStreamer plug-in modules and some of the dependencies Overscan relies on. Don’t let the naming conventions of these plugin packs confuse you — the gst-plugins-bad package isn’t bad per say; it won’t harm you or your machine. It’s bad because it doesn’t conform to some of the standards and expectations of the core GStreamer codebase (i.e. it isn’t well documented or doesn’t include tests).

  brew install gst-plugins-base --with-pango

When installing the base plugins, be sure to include Pango, a text layout library used by GTK+. Overscan uses this for working with text overlays while streaming.

  brew install gst-plugins-good --with-aalib --with-libvpx

AAlib is a library for converting still and moving images to ASCII art. Not necessary, but cool.

  brew install gst-plugins-bad --with-rtmpdump --with-fdk-aac

RTMPDump is a toolkit for RTMP streams. Fraunhofer FDK AAC is an encoder for AAC audio.

  brew install gst-plugins-ugly --with-x264

x264 is a library for encoding video streams into the H.264/MPEG-4 AVC format.

With these dependencies in place and a running Racket implementation, you are now ready to begin broadcasting. Personally, I have installed Racket with brew cask install racket

1.2 Basic Usage

The "Hello, world" of Overscan is a test broadcast:

#lang overscan

(broadcast (videotestsrc)

(audiotestsrc)

(filesink "/dev/null"))

This code will broadcast SMTPE color bars and a 440 Hz tone and write the resulting stream out to /dev/null. Additionally, a preview window will appear to display the video source, and the tone will play over your default audio output.

The core concept of Overscan revolves around the broadcast. To stop this broadcast you would call:

#lang overscan

(stop)

The three arguments to broadcast are GStreamer elements. The first is a source element for generating a video signal (e.g. a videotestsrc). The second, a source for generating audio (e.g. an audiotestsrc). A GStreamer pipeline is created to encode and mux these two sources and then send them on to the third and final argument, a sink element that accepts an flv container stream (e.g. a rtmpsink). By abstracting away the details of GStreamer pipeline construction, Overscan allows you to focus on the basic building blocks of live streaming.