INTRO

Pressing 'R' in the status window will start a recording.  Pressing it again
will stop recording.  Note that if you change channels while recording, the
recording will carry on recording the original stream that it started with.  It
doesn't follow your channel selection.  When a recording is in process you will
see [R] in the status window title.

After starting a recording a confirmation dialog will pop up.  If there is a
mencoder error you will be notified.  Note that it is necessary to have a 2
second delay to allow mencoder to start and test if it has successfully started
recording.

Pressing 'r' in the status window will bring up the recording menu.  There you
can view, playback and delete recordings.

Recordings are made using mencoder, which is part of the MPlayer package.  It
should copy most mp3 streams with no problems.

You can reencode to other formats, like aac etc, if you have the required
encoders and extra libraries installed.  You may need to rebuild MPlayer and
the extra libraries will be auto-detected during configure.  The SlackBuild for
MPlayer can be found on your nearest mirror in the source/xap/MPlayer
directory:

https://mirrors.slackware.com/slackware/slackware64-(release)/source/xap/MPlayer/

By default mencoder supports mp2 and ac3 encoding without any extra external
codecs needed.

Note that mencoder doesn't support the -playlist flag like mplayer does, so
playlist files are downloaded using wget and then sedded for the source audio
URL.  It's possible that the regex could fail so I'd be pleased to have any
problem ones mailed to me at dave@dawoodfall.net so that I can adjust the
regex.  Playlists are saved in a temp dir (/tmp/soma-xxxxxx) but the directory
is deleted on exit.

When playing back a recording, the playback duration is detected by querying
the file with 'soxi -d' (part of the the sox package), but it doesn't work on
all media types (eg ac3 and aac).

RECORDING OPTIONS

Technical Note: Recording audio-only files with mencoder requires a bit of a
hack that makes mencoder believe that it's recording a 1x1 px video.
Therefore, the mencoder options are a bit convoluted and are split up to make
it easier to set custom ouput encodings.  They are then assembled in the
correct order to feed to mencoder.

The defaults are to copy the stream.  For mp3 streams this should work fine.

Slackware's mencoder supports encoding to mp2 or ac3 (Dolby Digital) with no
extra libraries required.  If you use ac3 you should also be able to change the
channel layout and/or add channels.  For other formats you will need to install
extra encoders and rebuild MPlayer.


MENCODEROPTS (Source Stream Options)

This sets up the fake video and a raw audio output format.  You probably won't
need to touch this.

Default: -demuxer rawvideo -rawvideo w=1:h=1 -ovc copy -of rawaudio -audiofile


MENCODEROAC (Output Audio Codec)

This is where the encoder options are set, and controls the output.  This is
what you will be using to set up the desired output format.

Default: -oac copy

Examples:

-oac copy (just copies the stream)
-oac lavc -lavcopts acodec=ac3 (encodes to ac3 aka Dolby Digital)
-oac lavc -lavcopts acodec=mp2 (encodes to mpeg I layer 2)

Most stations use mp3 streams and '-oac copy' works fine, but some use aac (eg
BBC Radio 3) and copying the stream won't work.  For those stations you can
encode to another format and adjust the bit rate to match the source by setting
abitrate=N in -lavcopts (you should see the bitrate in soma's status window.
If it doesn't show, try pressing 'A' to toggle audio info.  Mencoder encodes
ac3 and mp2 at 224k bits by default unless you specifically set a rate).


AUTOSETBITRATE (Try to Set The Bitrate Automatically)

If '-oac lavc' is used then curl is used to grab the header from the stream URL
and if it contains 'icy-br' then the bitrate is set from that (if one isn't
already set manually.)  Note, this isn't guaranteed to work everywhere.

Default: on


RECEXT (Output Filename Extension):

mp3, mp2, ac3, aac etc.

Default: mp3


AUTOSETRECEXT (Try To Set RECEXT Automatically)

If this is set then soma will look to see if there is an 'acodec=' part in
MENCODEROAC.  If there is it will set the file extension to that.

Default: on


A fully assembled mencoder command will look something like this:

mencoder -demuxer rawvideo -rawvideo w=1:h=1 -ovc copy -of rawaudio \\
-audiofile "URL" -o "filename.ext" -oac lavc -lavcopts acodec=ac3:abitrate=N \\
"URL"

Note that the URL is specified twice.

The filename is constructed from the station name + 24 hour date and time and
saved to ~/.soma/recordings/.  Example: 'SF_10-33_20180418_112952.mp3'


ENCODING COMPARISONS

One hour recordings (approx).

Source audio stream: MP3, 128 kbps, 44.1 kHz, Stereo (SF 10-33 on SomaFM):

File Size  Encoder   Settings
54M        MP3       -oac copy
57M        AC3       -oac lavc -lavcopts acodec=ac3:abitrate=128

Source audio stream: AAC, 320 kbps, 48 kHz, Stereo (BBC Radio 3):

File Size  Encoder   Settings
138M       AC3       -oac lavc -lavcopts acodec=ac3:abitrate=320
105M       AAC       -oac faac -faacopts br=320 (mencoder compiled with faac)

Some frame skipping with 320k.

It was hard to notice any difference in audio quality between the ac3 and aac
versions, but as you can see there's a bit of a difference in file size.
MPlayer reports the aac bitrate as 270 kbps rather than 320, and according to
the man page it's an 'average' bitrate setting.

The obvious choice here is to use '-oac copy' on mp3 streams.  That should
match the quality of the source with no extra bits taking up diskspace or CPU
on playback.  Use ac3, mp2 or a custom encoder with lavc on non-mp3 streams,
with the bitrate set automatically if possible.

It's worth doing a test run before a starting long recording session.  Record
10 seconds or so, then press 'r' to bring up the recording menu, select 'View
Recordings' and play back the short test file, checking that the bitrate
matches the source.  If you don't see the codec info, press 'A' to toggle it
on.  If looks OK, reconnect to the station to do the real recording.


DEBUGGING

When a recording is started a ~/.soma/recordings/.mencoder.log will be made.
You can 'tail -f' this in another terminal to watch the output for info and
errors.

There will also be a .mencoder.url and .mencoder.cmd which show the URL and
full command used.
