.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "RTPENGINE-RECORDING 1"
.TH RTPENGINE-RECORDING 1 "2023-02-22" "10.5.3.5-1" "NGCP rtpengine"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
rtpengine\-recording \- media recording daemon for Sipwise rtpengine
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrtpengine-recording\fR [\fIoption\fR...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Sipwise rtpengine media proxy has support for exporting media (\s-1RTP\s0) packets
that it forwards. The rtpengine-recording daemon collects these exported
packets and decodes them into an audio format that can be listened to.
.SH "OPTIONS"
.IX Header "OPTIONS"
All options can (and should) be provided in a config file instead of
at the command line. See the \fB\-\-config\-file\fR option below for details.
.PP
If no options are given, then default values are assumed, which should be
sufficient for a standard installation of rtpengine.
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Print the usage information.
.IP "\fB\-v\fR, \fB\-\-version\fR" 4
.IX Item "-v, --version"
If called with this option, the \fBrtpengine-recording\fR daemon will simply print
its version number and exit.
.IP "\fB\-\-config\-file=\fR\fI\s-1FILE\s0\fR" 4
.IX Item "--config-file=FILE"
Specifies the location of a config file to be used. The config file is an
\&\fI.ini\fR style config file, with all command-line options listed here also
being valid options in the config file.
For all command-line options, the long name version instead of the
single-character version (e.g. \fBtable\fR instead of just \fBt\fR) must be
used in the config file.
For boolean options that are either present or not (e.g. \fBoutput-mixed\fR), a
boolean value (either \fBtrue\fR or \fBfalse\fR) must be used in the config file.
If an option is given in both the config file and at the command line,
the command-line value overrides the value from the config file.
.Sp
As a special value, \fBnone\fR can be passed here to suppress loading of the
default config file.
.IP "\fB\-\-config\-section=\fR\fI\s-1STRING\s0\fR" 4
.IX Item "--config-section=STRING"
Specifies the \fI.ini\fR style section to be used in the config file.
Multiple sections can be present in the config file, but only one can be
used at a time.
The default value is \fBrtpengine-recording\fR.
A config file section is started in the config file using square brackets
(e.g. \fB[rtpengine\-recording]\fR).
.IP "\fB\-L\fR, \fB\-\-log\-level=\fR\fI\s-1INT\s0\fR" 4
.IX Item "-L, --log-level=INT"
Takes an integer as argument and controls the highest log level which
will be sent to syslog.
The log levels correspond to the ones found in the \fBsyslog\fR\|(3) man page.
The default value is \fB6\fR, equivalent to \s-1LOG_INFO.\s0
The highest possible value is \fB7\fR (\s-1LOG_DEBUG\s0) which will log everything.
.IP "\fB\-\-log\-facilty=\fR\fBdaemon\fR|\fBlocal0\fR|...|\fBlocal7\fR|..." 4
.IX Item "--log-facilty=daemon|local0|...|local7|..."
The syslog facilty to use when sending log messages to the syslog daemon.
Defaults to \fBdaemon\fR.
.IP "\fB\-E\fR, \fB\-\-log\-stderr\fR" 4
.IX Item "-E, --log-stderr"
Log to stderr instead of syslog.
Only useful in combination with \fB\-\-foreground\fR.
.IP "\fB\-\-split\-logs\fR" 4
.IX Item "--split-logs"
Split multi-line log messages into individual log messages so that each
line receives its own log line prefix.
.IP "\fB\-\-no\-log\-timestamps\fR" 4
.IX Item "--no-log-timestamps"
Don't add timestamps to log lines written to stderr.
Only useful in combination with \fB\-\-log\-stderr\fR.
.IP "\fB\-\-log\-mark\-prefix=\fR\fI\s-1STRING\s0\fR" 4
.IX Item "--log-mark-prefix=STRING"
Prefix to be added to particular data fields in log files that are deemed
sensitive and/or private information. Defaults to an empty string.
.IP "\fB\-\-log\-mark\-suffix=\fR\fI\s-1STRING\s0\fR" 4
.IX Item "--log-mark-suffix=STRING"
Suffix to be added to particular data fields in log files that are deemed
sensitive and/or private information. Defaults to an empty string.
.IP "\fB\-p\fR, \fB\-\-pidfile=\fR\fI\s-1FILE\s0\fR" 4
.IX Item "-p, --pidfile=FILE"
Specifies a path and file name to write the daemon's \s-1PID\s0 number to.
.IP "\fB\-f\fR, \fB\-\-foreground\fR" 4
.IX Item "-f, --foreground"
If given, prevents the daemon from daemonizing, meaning it will stay in
the foreground.
Useful for debugging.
.IP "\fB\-t\fR, \fB\-\-table=\fR\fI\s-1INT\s0\fR" 4
.IX Item "-t, --table=INT"
Takes an integer argument. The value must match the \fBtable\fR option given to
the \fBrtpengine\fR media proxy to use for in-kernel packet forwarding.
Defaults to \fB0\fR if not specified.
.IP "\fB\-\-spool\-dir=\fR\fI\s-1PATH\s0\fR" 4
.IX Item "--spool-dir=PATH"
The path given here must match the \fBrecording-dir\fR path given to the
\&\fBrtpengine\fR media proxy. Defaults to \fI/var/spool/rtpengine\fR. The path must
reside on a file system that supports the \fBinotify\fR mechanism.
.IP "\fB\-\-num\-threads=\fR\fI\s-1INT\s0\fR" 4
.IX Item "--num-threads=INT"
How many worker threads to launch. Defaults to the number of \s-1CPU\s0 cores
available, or \fB8\fR if there are fewer than that or if the number is not
known.
.IP "\fB\-\-thread\-stack=\fR\fI\s-1INT\s0\fR" 4
.IX Item "--thread-stack=INT"
Set the stack size of each thread to the value given in kB. Defaults to 2048
kB. Can be set to \-1 to leave the default provided by the \s-1OS\s0 unchanged.
.IP "\fB\-\-output\-storage=\fR\fBfile\fR|\fBdb\fR|\fBboth\fR" 4
.IX Item "--output-storage=file|db|both"
Where to store media files. By default, media files are written directly to the
file system (see \fBoutput-dir\fR). They can also be stored as a \fB\s-1BLOB\s0\fR in a
MySQL database, either instead of, or in addition to, being written to the file
system.
.IP "\fB\-\-output\-dir=\fR\fI\s-1PATH\s0\fR" 4
.IX Item "--output-dir=PATH"
Path for media files to be written to if file output is enabled. Defaults to
\&\fI/var/lib/rtpengine\-recording\fR. The path must not be the same as used for the
\&\fBspool-dir\fR.
.IP "\fB\-\-output\-pattern=\fR\fI\s-1STRING\s0\fR" 4
.IX Item "--output-pattern=STRING"
File name pattern to be used for recording files. The pattern can reference
sub-directories. Parent directories will be created on demand. The default
setting is \fB\f(CB%c\fB\-%t\fR.
.Sp
The pattern must include \fBprintf\fR\-style format sequences. Supported format
sequences are:
.RS 4
.IP "\fB%%\fR" 4
.IX Item "%%"
A literal percent sign.
.IP "\fB\f(CB%c\fB\fR" 4
.IX Item "%c"
The call \s-1ID.\s0 It is mandatory for the output pattern to include this format
sequence.
.IP "\fB\f(CB%t\fB\fR" 4
.IX Item "%t"
The stream type. For \fBsingle\fR streams this is the \s-1SSRC\s0 written as hexadecimal;
for \fBmix\fR stream this is the string \fBmix\fR. It is mandatory for the output
pattern to include this format sequence.
.IP "\fB\f(CB%l\fB\fR" 4
.IX Item "%l"
The label for the participating party as communicated from the controlling
daemon.
.IP "\fB\f(CB%Y\fB\fR" 4
.IX Item "%Y"
.PD 0
.IP "\fB\f(CB%m\fB\fR" 4
.IX Item "%m"
.IP "\fB\f(CB%d\fB\fR" 4
.IX Item "%d"
.IP "\fB\f(CB%H\fB\fR" 4
.IX Item "%H"
.IP "\fB\f(CB%M\fB\fR" 4
.IX Item "%M"
.IP "\fB\f(CB%S\fB\fR" 4
.IX Item "%S"
.PD
These format sequence reference the current system time (when the output file
was created) and are the same as the format sequences supported by \fBdate\fR\|(1)
or \fBstrftime\fR\|(3) (year, month, day, hours, minutes, and seconds,
respectively).
.IP "\fB\f(CB%u\fB\fR" 4
.IX Item "%u"
Microseconds, expanded to 6 digits (\fB000000\fR through \fB999999\fR).
.IP "\fB%\fR\fI\s-1INT\s0\fR" 4
.IX Item "%INT"
References a prefix from the call \s-1ID\s0 of the given length. If this format
sequence is present more than once, then the prefixes are cumulative. For
example, if the call \s-1ID\s0 is \fBabcdefgh\fR and the output pattern is configured as
\&\fB\f(CB%2\fB/%3/%c\fR, then the resulting output file name would be \fBab/cde/abcdefgh\fR.
.RE
.RS 4
.RE
.IP "\fB\-\-output\-format=\fR\fBwav\fR|\fBmp3\fR|\fBnone\fR" 4
.IX Item "--output-format=wav|mp3|none"
File format to be used for media files that are produced. Defaults to \s-1PCM WAV\s0
(\s-1RIFF\s0) files. Applicable for both files stored on the file system and in a
database. If \fBnone\fR is selected then file output is disabled.
.IP "\fB\-\-resample\-to=\fR\fI\s-1INT\s0\fR" 4
.IX Item "--resample-to=INT"
Resample all audio to the given sample rate (e.g. \fB48000\fR). Resampling is
disabled by default, meaning that files will be written with the same sample
rate as the source media.
.IP "\fB\-\-mp3\-bitrate=\fR\fI\s-1INT\s0\fR" 4
.IX Item "--mp3-bitrate=INT"
If \s-1MP3\s0 output is selected, use the given bitrate for the \s-1MP3\s0 encoder (e.g.
\&\fB64000\fR). There is no default value, so this option must be given if \s-1MP3\s0
output is selected. Note that not all bitrates are valid in combinations with
all sample rates. For \s-1MP3\s0 output it's therefore recommended to also set
\&\fBresample-to\fR.
.IP "\fB\-\-output\-mixed\fR" 4
.IX Item "--output-mixed"
.PD 0
.IP "\fB\-\-output\-single\fR" 4
.IX Item "--output-single"
.PD
Whether to produce \fBmixed\fR audio files, or \fBsingle\fR audio files, or both. If
neither option is given, then by default both are enabled. If no file output is
desired, set \fBoutput-format\fR to \fBnone\fR.
.Sp
A \fBsingle\fR audio file contains the audio for a single \s-1RTP SSRC,\s0 which usually
means an unidirectional audio stream. These are decoded directly from an \s-1RTP\s0
stream and do not take timestamping into account, meaning that gaps or pauses
in the \s-1RTP\s0 stream are not reflected in the output audio file.
.Sp
A \fBmixed\fR audio file consists of the first four \s-1RTP SSRC\s0 seen, mixed together
into a single output file, which usually means that a bidirectional audio
stream is produced. Audio mixing takes \s-1RTP\s0 timestamping into account, so gaps
and pauses in the \s-1RTP\s0 media are reflected in the output audio to keep the
multiple audio sources in sync.
.IP "\fB\-\-mix\-method=\fR\fBdirect\fR|\fBchannels\fR" 4
.IX Item "--mix-method=direct|channels"
Selects a method to mix multiple audio inputs into a single output file for
\&\fBmixed\fR output. The default is \fBdirect\fR which directly mixes all audio inputs
together, producing a mixed output file with the same format as an audio file
from a single input (\fBoutput-single\fR) would be.
.Sp
The \fBchannels\fR mixing method puts each audio input into its own audio channel
in the output file, therefore producing a multi-channel output file. Up to four
separate \s-1RTP\s0 SSRCs are supported for a mixed output, which means that if each
input is mono audio, then the mixed output file would contain 4 audio channels.
This mixing method requires an output file format which supports these kinds of
multi-channel audio formats (e.g. \fBwav\fR).
.IP "\fB\-\-output\-chmod=\fR\fI\s-1INT\s0\fR" 4
.IX Item "--output-chmod=INT"
Change the file permissions of recording files to the given mode. Must be given
as an octal integer, for example \fB0660\fR.
.IP "\fB\-\-output\-chmod\-dir=\fR\fI\s-1INT\s0\fR" 4
.IX Item "--output-chmod-dir=INT"
Change the file permissions of recording files to the given mode. Must be given
as an octal integer, for example \fB0700\fR (which is also the default value).
.IP "\fB\-\-output\-chown=\fR\fI\s-1USER\s0\fR|\fI\s-1UID\s0\fR" 4
.IX Item "--output-chown=USER|UID"
.PD 0
.IP "\fB\-\-output\-chgrp=\fR\fI\s-1GROUP\s0\fR|\fI\s-1GID\s0\fR" 4
.IX Item "--output-chgrp=GROUP|GID"
.PD
Change the ownership of recording files. Either user/group names or numeric IDs
are supported. If the value is blank or given as \fB\-1\fR then the user/group is
left unchanged.
.IP "\fB\-\-mysql\-host=\fR\fI\s-1HOST\s0\fR|\fI\s-1IP\s0\fR" 4
.IX Item "--mysql-host=HOST|IP"
.PD 0
.IP "\fB\-\-mysql\-port=\fR\fI\s-1INT\s0\fR" 4
.IX Item "--mysql-port=INT"
.IP "\fB\-\-mysql\-user=\fR\fI\s-1USERNAME\s0\fR" 4
.IX Item "--mysql-user=USERNAME"
.IP "\fB\-\-mysql\-pass=\fR\fI\s-1PASSWORD\s0\fR" 4
.IX Item "--mysql-pass=PASSWORD"
.IP "\fB\-\-mysql\-db=\fR\fI\s-1STRING\s0\fR" 4
.IX Item "--mysql-db=STRING"
.PD
Configuration for a MySQL storage backend. Details about calls and media files
that are produced are stored into the database. Optionally the media files
themselves can be stored as well (see \fBoutput-storage\fR).
.IP "\fB\-\-forward\-to=\fR\fI\s-1PATH\s0\fR" 4
.IX Item "--forward-to=PATH"
Forward raw \s-1RTP\s0 packets to a Unix socket. Disabled by default.
.IP "\fB\-\-tls\-send\-to=\fR\fI\s-1IP\s0\fR\fB:\fR\fI\s-1PORT\s0\fR" 4
.IX Item "--tls-send-to=IP:PORT"
.PD 0
.IP "\fB\-\-tls\-resample=\fR\fI\s-1INT\s0\fR" 4
.IX Item "--tls-resample=INT"
.PD
Send decoded audio over a \s-1TCP TLS\s0 connection to the specified destination.
Audio is sent as raw mono 16\-bit \s-1PCM\s0 in the given sample rate.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
.IP "\fB0\fR" 4
.IX Item "0"
Successful termination.
.IP "\fB1\fR" 4
.IX Item "1"
An error occurred.
.SH "FILES"
.IX Header "FILES"
.IP "\fI/etc/rtpengine/rtpengine\-recording.conf\fR" 4
.IX Item "/etc/rtpengine/rtpengine-recording.conf"
Configuration file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBrtpengine\fR\|(8).