Fix Markdown

README.md

@@ -1,11 +1,15 @@
 # GStreamer command-line cheat sheet
 
-This series of docs provides a cheat sheet for GStreamer on the command-line.
+[GStreamer](https://gstreamer.freedesktop.org/) is a powerful library for manipulating audio and video - including live streams. This repo provides:
 
-A few Python examples are also [included](python_examples/) for when you need GStreamer to be dynamic (i.e. react to user or some other action).
+*  a cheat sheet for GStreamer on the command-line, and
+*  a few [Python examples](python_examples/). 
+
+Whilst the command line is great, programmatic usage (in Python or another language) allows you to dynamically manipulate the A/V streams.
 
 ## Contents
 
+* [Installing](installing.md)
 * [Basics](basics.md)
 * [Test streams](test_streams.md)
 * [RTMP](rtmp.md)
@@ -21,16 +25,15 @@ A few Python examples are also [included](python_examples/) for when you need GS
 
 ## Sources and references
 
-* [Basic command line reference](http://docs.gstreamer.com/display/GstSDK/Basic+tutorial+10%3A+GStreamer+tools)
+* [Basic command line reference](https://gstreamer.freedesktop.org/documentation/tutorials/basic/gstreamer-tools.html?gi-language=c)
 * [Pipeline examples](https://gstreamer.freedesktop.org/documentation/tools/gst-launch.html#pipeline-examples)
-* [List of all Gstreamer plugins](https://gstreamer.freedesktop.org/documentation/plugins.html)
+* [List of all Gstreamer plugins](https://gstreamer.freedesktop.org/documentation/plugins_doc.html?gi-language=c)
 * [Handy elements](https://gstreamer.freedesktop.org/documentation/tutorials/basic/handy-elements.html#uridecodebin)
 
 ## Other cheat-sheets
 
-* http://wiki.oz9aec.net/index.php/Gstreamer_cheat_sheet
-* https://github.com/xmementoit/gstreamerCheatsheet/blob/master/README.md
-* https://gist.github.com/nebgnahz/26a60cd28f671a8b7f522e80e75a9aa5
+* <https://github.com/xmementoit/gstreamerCheatsheet/blob/master/README.md>
+* <https://gist.github.com/nebgnahz/26a60cd28f671a8b7f522e80e75a9aa5>
 
 ## Interacting with the GStreamer pipeline
 
@@ -64,4 +67,4 @@ If you spot anything incorrect or incomplete, reports are welcome, either using
 
 # My GStreamer project
 
-Creating this guide gave me enough GStreamer understanding to make [Brave](https://github.com/bbc/brave), a live video editor for the cloud.
+Creating this guide gave me enough GStreamer understanding to make a prototype [Brave](https://github.com/bbc/brave), a live video editor for the cloud. (Regrettably this prototype has not been updated in a few years.)

basics.md

@@ -1,6 +1,5 @@
 # Basics (GStreamer command-line cheat sheet)
 
-
 ## Playing content
 
 These examples assume that bash variable `SRC` to be set to a video file (e.g. an mp4 file). You can do this by, e.g.
@@ -9,8 +8,7 @@ These examples assume that bash variable `SRC` to be set to a video file (e.g. a
 export SRC=/home/me/videos/test.mp4
 ```
 
-
-### Play a video (with audio)
+### Play a video (with audio)
 
 The magical element `playbin` can play anything:
 
@@ -30,7 +28,6 @@ gst-launch-1.0 filesrc location=$SRC ! \
     decodebin ! videoconvert ! videoscale ! autovideosink
 ```
 
-
 ### Play a video (no audio)
 
 ```
@@ -43,14 +40,13 @@ which could also have been done as:
 gst-launch-1.0 -v filesrc location="$SRC" ! decodebin ! autovideosink
 ```
 
-
-### Play just the audio from a video
+### Play just the audio from a video
 
 ```
 gst-launch-1.0 -v uridecodebin uri="file://$SRC" ! autoaudiosink
 ```
 
-### Visualise the audio:
+### Visualise the audio:
 
 ```
 gst-launch-1.0 filesrc location=$SRC ! qtdemux name=demux  demux.audio_0 ! queue ! decodebin ! audioconvert ! wavescope ! autovideosink
@@ -66,7 +62,7 @@ gst-launch-1.0 filesrc location=$SRC ! decodebin ! tee name=t ! queue ! audiocon
 
 ### Add filters
 
-Go slightly mad:
+Here's the 'vertigo' filter:
 
 ```
 gst-launch-1.0 -v filesrc location="$SRC" ! decodebin ! videoconvert ! vertigotv ! autovideosink
@@ -74,7 +70,7 @@ gst-launch-1.0 -v filesrc location="$SRC" ! decodebin ! videoconvert ! vertigotv
 
 Try also ‘rippletv’, ‘streaktv’, ‘radioactv’, ‘optv’, ‘quarktv’, ‘revtv’, ‘shagadelictv’, ‘warptv’ (I like), ‘dicetv’, ‘agingtv’ (great), ‘edgetv’ (could be great on real stuff)
 
-### Add A clock
+### Add a clock
 
 ```
 gst-launch-1.0 -v filesrc location="$SRC" ! decodebin ! clockoverlay font-desc="Sans, 48" ! videoconvert ! autovideosink
@@ -88,7 +84,7 @@ gst-launch-1.0 -v filesrc location="$SRC" ! decodebin ! videoconvert ! videoscal
 
 ### Change framerate
 
-Changing framerate is quiet common, as the world does not have a consistent standard. Facebook Live wants 30fps, YouTube wants 30 or 60fps. There's a nice summary on the  [Apple FCP site](https://documentation.apple.com/en/finalcutpro/usermanual/index.html#chapter=D%26section=4%26tasks=true).
+Changing framerate is quiet common, as the world does not have a consistent standard. Facebook Live wants 30fps, for example. 
 
 Change framerate:
 
@@ -117,7 +113,7 @@ gst-launch-1.0 filesrc location=$SRC ! \
     autovideosink
 ```
 
-### Play an MP3 audio file
+### Play an MP3 audio file
 
 Set the environment variable `$AUDIO_SRC` to be the location of the MP3 file. Then:
 

images.md

@@ -46,7 +46,7 @@ The `pngenc` element can create a single PNG:
 gst-launch-1.0 videotestsrc ! pngenc ! filesink location=foo.png
 ```
 
-### Capture an image as JPEG
+### Capture an image as JPEG
 
 The `jpegenc` element can create a single JPEG:
 

installing.md

@@ -0,0 +1,50 @@
+# Installing (GStreamer command-line cheat sheet)
+
+## Packages
+
+Installing GStreamer is not enough. GStreamer is built on a large number of plugins, which are split into four packages:
+
+* *Base*: Reliable, commonly used, high-quality plug-ins
+* *Good*: Additional plug-ins that are also reliable and high-quality
+* *Bad*: Plugins that are potentially unreliable
+* *Ugly*: Plugins that may bring concerns, often around licensing
+
+(Full definition of these packages [in this readme](https://gitlab.freedesktop.org/gstreamer/gstreamer/-/blob/main/subprojects/gst-plugins-bad/README.md).)
+
+You can choose which you install - you'll almost certainly need base, and potentially the others.
+
+You can see which package a plugin belongs in the [Plugins API reference](https://gstreamer.freedesktop.org/documentation/plugins_doc.html?gi-language=c).
+
+You can get a list of all installed plugins with:
+
+```
+gst-inspect-1.0
+```
+
+## Installing on MacOS
+
+The easiest way to install on MacOS is using Homebrew. There is a [GStreamer](https://formulae.brew.sh/formula/gstreamer) package, and additional packages for the base/good/bad/ugly plugins.
+
+Example:
+
+```
+brew install gstreamer gst-plugins-base gst-plugins-good
+```
+
+There are many dependencies so this can take time to run!
+
+You can also compile and install yourself - see (https://gstreamer.freedesktop.org/documentation/installing/on-mac-osx.html).
+
+
+## Installing on Ubuntu Linux
+
+The GStreamer APT packages are excellent. 
+
+For a good install command, see (https://gstreamer.freedesktop.org/documentation/installing/on-linux.html?gi-language=c).
+
+
+
+## Installing on other platfoms
+
+See (https://gstreamer.freedesktop.org/documentation/installing/index.html?gi-language=c)
+

mixing.md

@@ -98,7 +98,7 @@ gst-launch-1.0   \
 Use the `audiomixer` element to mix audio. It replaces the `adder` element, which struggles under some circumstances (according to the [GStreamer 1.14 release notes](https://gstreamer.freedesktop.org/releases/1.14/)).
 
 
-### Mix two (or more) test audio streams
+### Mix two (or more) test audio streams
 
 Here we use two different frequencies (tones):
 
@@ -110,7 +110,7 @@ gst-launch-1.0 \
 ```
 
 
-### Mix two test streams, dynamically
+### Mix two test streams, dynamically
 
 [This Python example](python_examples/audio_dynamic_add.py) shows a dynamic equivalent of this example - the second test source is only mixed when the user presses Enter.
 
@@ -127,7 +127,7 @@ gst-launch-1.0 \
 ```
 
 
-### Mix a test stream with an MP3 file
+### Mix a test stream with an MP3 file
 
 Because the audio streams are from different sources, they must each be passed through `audioconvert`.
 
@@ -139,7 +139,7 @@ gst-launch-1.0 \
 ```
 
 
-## Mixing video & audio together
+## Mixing video & audio together
 
 
 ### Mix two fake video sources and two fake audio Sources
@@ -256,7 +256,7 @@ gst-launch-1.0 \
     demux2. ! queue2 ! decodebin ! videoconvert ! videoscale ! video/x-raw,width=320,height=180 ! videomix.
 ```
 
-## Fading
+## Fading
 It's often nicer to fade between sources than to abruptly cut betwen them. This can be done both with video (temporarily blending using alpha channel) or audio (lowering the volume of one whilst raising it on another).
 
 It's not possible to do this on the command line... alhough `alpha` and `volume` can be set, they can only be set to discrete values.

network_transfer.md

@@ -83,13 +83,13 @@ gst-launch-1.0 \
     rtpmp2tdepay ! decodebin name=decoder ! autoaudiosink  decoder. ! autovideosink
 ```
 
-### How to receive with VLC
+### How to receive with VLC
 
 To receive a UDP stream, an `sdp` file is required. An example can be found at https://gist.github.com/nebgnahz/26a60cd28f671a8b7f522e80e75a9aa5
 
 ## TCP
 
-### Audio via TCP
+### Audio via TCP
 
 To send a test stream:
 

queues.md

@@ -22,7 +22,7 @@ gst-launch-1.0 videotestsrc ! queue ! autovideosink
 Queues add latency, so the general advice is not to add them unless you need them.
 
 
-## Queue2
+## Queue2
 
 Confusingly, `queue2` is not a replacement for `queue`. It's not obvious when to use one or the other.
 

rtmp.md

@@ -144,7 +144,7 @@ gst-launch-1.0 videotestsrc is-live=true ! \
     voaacenc bitrate=96000 ! audio/mpeg ! aacparse ! audio/mpeg, mpegversion=4 ! mux.
 ```
 
-### Send a file over RTMP
+### Send a file over RTMP
 
 Audio & video:
 

sharing_and_splitting_pipelines.md

@@ -77,7 +77,7 @@ I've used `proxysink` and `proxysrc` to split larger pipelines into smaller ones
 Unlike _inter_ below, _proxy_ will keep timing in sync. This is great if it's what you want... but if you want pipelines to have their own timing, it might not be right for your needs..
 
 
-### gstproxy documentation
+### gstproxy documentation
 
 * Introduced by the blog mentioned above (http://blog.nirbheek.in/2018/02/decoupling-gstreamer-pipelines.html)
 * Example code on proxysrc here: https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-bad-plugins/html/gst-plugins-bad-plugins-proxysrc.html
@@ -108,7 +108,7 @@ A slightly more interesting example can be found at
 * that when the video ends, the other pipelines continue.
 
 
-## inter (intervideosink/intervideosrc and their audio & subtitle counterparts)
+## inter (intervideosink/intervideosrc and their audio & subtitle counterparts)
 
 The 'inter' versions of 'proxy' are dumber. They don't attempt to sync timings. But this can be useful if you want pipelines to be more independent. (Pros and cons on this discussed [here](http://gstreamer-devel.966125.n4.nabble.com/How-to-connect-intervideosink-and-intervideosrc-for-IPC-pipelines-td4684567.html).)
 

srt.md

@@ -20,7 +20,7 @@ And create a receiver client like this:
 gst-launch-1.0 -v srtclientsrc uri="srt://127.0.0.1:8888" ! decodebin ! autovideosink
 ```
 
-## Server receiving the AV
+## Server receiving the AV
 
 To have the server receiving, rather than sending, swap 'srtclientsrc' for 'srcserversrc'.
 Likewise, to have the client sending rather than receiving, swap 'srtserversink' for 'srtclientsink'.

tee.md

@@ -2,7 +2,7 @@
 
 This page describes the `tee` element, which allows audio & video streams to be sent to more than one place.
 
-## Tee to two local video outputs
+## Tee to two local video outputs
 
 Here's a simple example that sends shows video test source twice (using `autovideosink`)
 
@@ -14,7 +14,7 @@ gst-launch-1.0 \
     t. ! queue ! videoconvert ! autovideosink
 ```
 
-## Tee to two different video outputs
+## Tee to two different video outputs
 
 Here's an example that sends video to both `autovideosink` and a TCP server (`tcpserversink`).
 Note how `async=false` is required on both sinks, because the encoding step on the TCP branch takes longer, and so the timing will be different.
@@ -44,7 +44,7 @@ gst-launch-1.0 videotestsrc ! \
     t. ! queue ! x264enc ! mpegtsmux ! tcpserversink port=7001 host=127.0.0.1 recover-policy=keyframe sync-method=latest-keyframe
 ```
 
-## Tee on inputs
+## Tee on inputs
 
 You can also use `tee` in order to do multiple things with inputs. This example combines two audio visualisations:
 

test_streams.md

@@ -60,7 +60,7 @@ You can change the *volume* by setting the `volume` property between `0` and `1`
 gst-launch-1.0 audiotestsrc volume=0.1 ! autoaudiosink
 ```
 
-### White noise
+### White noise
 
 Set `wave` to `white-noise`:
 
@@ -70,7 +70,7 @@ gst-launch-1.0 audiotestsrc wave="white-noise" ! autoaudiosink
 
 There are variations (e.g. _red noise_) - see the [docs](https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-audiotestsrc.html) for a complete list.
 
-### Silence
+### Silence
 
 If you need an audio stream with nothing in:
 

writing_to_files.md

@@ -5,7 +5,7 @@ The [`filesink`](https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstre
 Note that, when using the command-line, the `-e` parameter ensures the output file is correctly completed on exit.
 
 
-### Write to an mp4 file
+### Write to an mp4 file
 
 This example creates a test video (animated ball moving, with clock), and writes it as an MP4 file.
 Also added is an audio test source - a short beep every second.