On this page:
make-broadcast
broadcast
get-current-broadcast
start
on-air?
stop
kill-broadcast
add-listener
remove-listener
graphviz
overscan-logger
2.1 Twitch
twitch-stream-key
twitch-sink
2.2 mac  OS
audio-sources
camera-sources
screen-sources
audio
camera
screen
osxvideosink
osxaudiosink
call-atomically-in-run-loop
2.3 Drawing
make-drawable
7.7

2 Broadcasting

A broadcast is a global pipeline that can be controlled through the Overscan DSL, and provides a global event bus.

procedure

(make-broadcast video-source 
  audio-source 
  flv-sink 
  #:name name 
  #:preview video-preview 
  #:monitor audio-monitor 
  #:h264-encoder h264-encoder 
  #:aac-encoder aac-encoder) 
  (or/c (is-a?/c pipeline%) #f)
  video-source : (is-a?/c element%)
  audio-source : (is-a?/c element%)
  flv-sink : (is-a?/c element%)
  name : (or/c string? false/c)
  video-preview : (is-a?/c element%)
  audio-monitor : (is-a?/c element%)
  h264-encoder : (is-a?/c element%)
  aac-encoder : (is-a?/c element%)
Create a pipeline that encodes a video-source into h264 with h264-encoder, an audio-source into aac with aac-encoder, muxes them together into an flv, and then sends that final flv to the flv-sink.

procedure

(broadcast [video-source    
  audio-source    
  flv-sink]    
  #:name name    
  #:preview video-preview    
  #:monitor audio-monitor    
  #:h264-encoder h264-encoder    
  #:aac-encoder aac-encoder)  (is-a?/c pipeline%)
  video-source : (is-a?/c element%) = (videotestsrc)
  audio-source : (is-a?/c element%) = (audiotestsrc)
  flv-sink : (is-a?/c element%)
   = (filesink (make-temporary-file))
  name : (or/c string? false/c)
  video-preview : (is-a?/c element%)
  audio-monitor : (is-a?/c element%)
  h264-encoder : (is-a?/c element%)
  aac-encoder : (is-a?/c element%)
Like make-broadcast, this procedure creates a pipeline, but will then call start to promote it to the current broadcast.

Gets the current broadcast or raises an error if there is none.

procedure

(start pipeline)  thread?

  pipeline : (is-a?/c pipeline%)
Transforms the given pipeline into the current broadcast by creating an event listener on its bus and setting its state to 'playing. The returned thread is the listener polling the pipeline’s bus.

procedure

(on-air?)  boolean?

Returns #t if there is a current broadcast, #f otherwise.

procedure

(stop [#:timeout timeout])

  (one-of/c 'failure 'success 'async 'no-preroll)
  timeout : exact-nonnegative-integer? = 5
Stops the current broadcast by sending an EOS event. If the state of the pipeline cannot be changed within timeout seconds, an error will be raised.

procedure

(kill-broadcast)  void?

Stops the current broadcast without waiting for a downstream EOS.

procedure

(add-listener listener)  exact-nonnegative-integer?

  listener : (-> message? (is-a?/c pipeline%) any)
Adds listener to the broadcast’s event bus, and returns an identifier that can be used with remove-listener. A separate thread of execution will call the listener whenever a message appears on the bus.

procedure

(remove-listener id)  void?

  id : exact-nonnegative-integer?
Removes the listener with id from the event bus.

procedure

(graphviz path [pipeline])  any

  path : path-string?
  pipeline : (is-a?/c pipeline%) = (get-current-broadcast)
Writes a graphviz dot file to path diagramming the pipeline.

A logger with a topic called 'Overscan. Used by Overscan’s event bus to log messages.

2.1 Twitch

 (require overscan/twitch) package: overscan

Twitch.tv is a live streaming community. To broadcast to Twitch, get a stream key from the dashboard settings and use it as a parameter to twitch-sink with twitch-stream-key.

parameter

(twitch-stream-key)  string?

(twitch-stream-key key)  void?
  key : string?
 = (getenv "TWITCH_STREAM_KEY")
A parameter that defines the current stream key for broadcasting to Twitch.tv.

procedure

(twitch-sink [#:test bandwidth-test?])  rtmpsink?

  bandwidth-test? : boolean? = #f
Create a rtmpsink set up to broadcast upstream data to Twitch.tv. If bandwidth-test? is #t, the stream will be configured to run a test, and won’t be broadcast live. This procedure can be parameterized with twitch-stream-key.

2.2 macOS

 (require overscan/macos) package: overscan

Overscan was developed primarily on a computer running macOS. This module provides special affordances for working with Apple hardware and frameworks.

Putting all the pieces together, to broadcast a camera and a microphone to Twitch, preview the video, and monitor the audio, you would call:

#lang overscan
(require overscan/macos)
 
(call-atomically-in-run-loop (λ ()
  (broadcast (camera 0)
             (audio 0)
             (twitch-sink)
             #:preview (osxvideosink)
             #:monitor (osxaudiosink))))

A vector of input audio devices available.

A vector of factory procedures for creating elements that correspond with the camera devices available.

A vector of factory procedures for creating elements that correspond with the screen capture devices available.

procedure

(audio pos)  (is-a?/c element%)

  pos : exact-nonnegative-integer?
Finds the audio device in slot pos of audio-sources and creates a source element corresponding to it.

procedure

(camera pos)  (is-a?/c element%)

  pos : exact-nonnegative-integer?
Finds the camera device in slot pos of camera-sources and creates a source element corresponding to it.

procedure

(screen pos    
  [#:capture-cursor cursor?    
  #:capture-clicks clicks?])  (is-a?/c element%)
  pos : exact-nonnegative-integer?
  cursor? : boolean? = #f
  clicks? : boolean? = #f
Finds the screen capture device in slot pos of screen-sources and creates a source element corresponding to it. When cursor? or clicks? are #t, the element will track the cursor or register clicks respectively.

procedure

(osxvideosink [name])  (element/c "osxvideosink")

  name : (or/c string? #f) = #f
Creates an element for rendering input into a macOS window. Special care needs to be taken to make sure that the Racket runtime plays nicely with this window. See call-atomically-in-run-loop.

procedure

(osxaudiosink [name])  (element/c "osxaudiosink")

  name : (or/c string? #f) = #f
Creates an element for rendering audio samples through a macOS audio output device.

procedure

(call-atomically-in-run-loop thunk)  any

  thunk : (-> any)
Because of the idiosyncrasies of Racket, GStreamer, and Cocoa working together in concert, wrap the state change of a pipeline that includes a osxvideosink in thunk and call with this procedure, otherwise the program will crash. I don’t fully understand the Cocoa happening underneath the hood, but a good rule of thumb is that if you have a broadcast that includes osxvideosink, wrap it in this procedure before calling it.

2.3 Drawing

 (require overscan/draw) package: overscan

procedure

(make-drawable element    
  [#:width width    
  #:height height])  
(or/c (is-a?/c bin%) #f)
(is-a?/c bitmap-dc%)
  element : (is-a?/c element%)
  width : exact-nonnegative-integer? = 1280
  height : exact-nonnegative-integer? = 720
Creates a means to draw on top of element using The Racket Drawing Toolkit. This procedure creates a drawing surface of width by height dimensions that overlays element. Two values are returned: a bin, or #f if an overlay could not be created, and a bitmap-dc% object for drawing operations.