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.
procedure
Gets the current broadcast or raises an error if there is none.
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.
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?
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
path : path-string? pipeline : (is-a?/c pipeline%) = (get-current-broadcast)
Writes a graphviz dot file to path diagramming the pipeline.
value
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 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))))
value
audio-sources : (vectorof (is-a?/c device%))
A vector of input audio devices available.
value
camera-sources : (vectorof (-> (is-a?/c element%)))
A vector of factory procedures for creating elements that correspond with the camera devices available.
value
screen-sources : (vectorof (-> (is-a?/c element%)))
A vector of factory procedures for creating elements that correspond with the screen capture devices available.
procedure
pos : exact-nonnegative-integer?
Finds the audio device in slot pos of audio-sources and creates a source element corresponding to it.
procedure
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.