MuMuDVB - README for the configuration of the transcoding
=========================================================

General information
-------------------


Compiling MuMuDVB with transcoding support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In order to compile MuMuDVB with transcoding you will need the following librairies: libavcodec, libavformat and libswscale

Then you have to add the --enable-transcoding flag to your configure. Ex: `./configure --enable-transcoding`

Check at the end of the configure that the transcoding is effectively enabled. If not there is probably a library missing.


Using transcoding
~~~~~~~~~~~~~~~~~

For transconding the stream you have to make a choice for three different parameters : 

- The video Codec (and it's encoding parameters)
- The audio Codec (and it's encoding parameters)
- The container (how the audio and video data are mixed together)


Future developments for transcoding
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Making it work with unicast, in particular RTSP

Common problems
~~~~~~~~~~~~~~~


Data queue is full.
^^^^^^^^^^^^^^^^^^^

If you get the message `Data queue is full`, this usually means that your system is too slow to transcode what you asked. Ie the video data arrives faster that your ability to transcode it.


Codec not found
^^^^^^^^^^^^^^^

If you get a message like `Couldn't find video encoder.` or `Couldn't find audio encoder.` this means that you don't have the codec you asked for installed on your system. You can check if you made a typo in the
codec name by <<list_codecs,listing the availaible codecs>>.

If the codec is really missing there is several solutions: 

- Install extra codecs (libavcodec-extra-* on debian/ubuntu)
- On debian, due to licence restrictions, you could try to install ffmpeg from the debian-multimedia repositories
- Compile ffmpeg yourself


Broken ffmpeg default settings detected
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you get a message saying "Broken ffmpeg default settings detected"

Adding the following options to your transcoding configuration will make it work

------------------------------
transcode_me_range=16
transcode_qdiff=4
transcode_qmin=10
transcode_qmax=51
------------------------------



The untranscoded stream is still sent
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For avoiding the original stream to be also sent, use the transcode_send_transcoded_only option


Placement of the options
~~~~~~~~~~~~~~~~~~~~~~~~

All the transcoding configuration concerning a channel has to come just after the channel it concerns.
If you define some transcoding option before any channel, this configuration will be common to all channels.

[[list_codecs]]
Listing the available codecs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To see the installed codecs on your system run MuMuDVB in verbose mode (one -v on the command line) with transcoding enabled and configured (ie transcode_enable=1). The available codecs will be displayed on the log output after the initialisation of avlibs.

Otherwise you can use the `ffmpeg -codecs` command (see `man ffmpeg` for more information on this command).

If your ffmpeg is not sufficiently recent, you can use `ffmpeg -formats` which will give you a clue.


Transcode and autoconfiguration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Transcoding should work with autoconfiguration, please report any problem.

Templates
~~~~~~~~~

You can use templates for the following options : 

- transcode_sdp_filename
- transcode_ffm_url
- transcode_rtp_port

In the case of *transcode_rtp_port* you can use mathematical expressions like "transcode_rtp_port=1000+%server*100+%number*2"

The allowed templates are: `%server`, `%card`, `%tuner` and `%number`;

Examples
--------

See the examples in the `doc/transcode/examples` directory



Options
-------

transcode_enable
~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* enables or disables transcoding

*Possible Values:* 0 - disable (default); 1 - enable.

transcode_send_transcoded_only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* Send only the transcoded stream

*Possible Values:* 0 - send both (default); 1 - send only the transcoded stream.

transcode_video_codec
~~~~~~~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* video codec for encoding

*Possible Values:* mpeg4 (for MPEG-4), libx264 (for H.264) etc.


transcode_audio_codec
~~~~~~~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* audio codec for encoding

*Possible Values:* libmp3lame (for MP3), libfaac (for AAC) etc.



transcode_streaming_type
~~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* streaming type

*Possible Values:* 

* mpegts - for MPEG-2 TS streaming.
* rtp - for RTP streaming.
* ffm - FFM feed to ffserver


transcode_ffm_url
~~~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* URL of FFM feed (required for FFM streaming)

*Allowed templates:* `%number`, `%card`, `%tuner` and `%server`

transcode_rtp_port
~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* base port for RTP streaming

Each RTP stream (audio or video) must go on an even port. MuMuDVB will took for
each media stream next even port starting from value specified in this option.

*Allowed templates:* `%number`, `%card`, `%tuner` and `%server`. You can use operations `*` and `+` like "transcode_rtp_port=1000+%server*100+%number*2"

transcode_sdp_filename
~~~~~~~~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* path to generated SDP file (for RTP streaming)

*Allowed templates:* `%number`, `%card`, `%tuner` and `%server`

transcode_video_scale
~~~~~~~~~~~~~~~~~~~~~

*Type:* <float>

*Description:* factor for video scaling


transcode_video_frames_per_second
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* FPS of output video


transcode_audio_channels
~~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* number of output audio channels

Common values are:
1 - mono
2 - stereo



transcode_audio_sample_rate
~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* output audio sample rate

Common values are: 96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350


transcode_aac_latm
~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* enable LATM payload type for AAC streams while RTP streaming

*Possible Values:* 

* 0 - disable (default)
* 1 - enable



transcode_aac_profile
~~~~~~~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* profile in case of AAC audio encoding

*Possible Values:* 

* low  - Low Complexity (LC) - the simplest and most widely used and supported.
* main - Main Profile (MAIN) - like the LC profile, with the addition of backwards prediction.
* ssl  - Sample-Rate Scalable (SRS) - a.k.a. Scalable Sample Rate (MPEG-4 AAC-SSR).
* ltp  - Long Term Prediction (LTP) - added in the MPEG-4 standard an improvement of the
          MAIN profile using a forward predictor with lower computational complexity.



transcode_video_bitrate
~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* set video bitrate (int bits/s)

Enables target bitrate mode for video. Attempts to reach a specific bitrate. Bitrate mode is generally the worst ratecontrol mode H.264 has.



transcode_audio_bitrate
~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* set audio bitrate (int bits/s)

Enables target bitrate mode for audio.



transcode_x264_profile
~~~~~~~~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* set H.264 encoding profile


*Possible Values:* 

* baseline - Baseline Profile

This is equivalent to :
-----------------------------------
transcode_coder_type=0
transcode_enable_8x8dct=0
transcode_loop_filter=1
transcode_sc_threshold=1
transcode_x264_partitions=1
transcode_video_codec=libx264
-----------------------------------

* main - Main Profile
This is equivalent to :
-----------------------------------
transcode_coder_type=1
transcode_enable_8x8dct=0
transcode_loop_filter=1
transcode_sc_threshold=1
transcode_x264_partitions=1
transcode_video_codec=libx264
-----------------------------------

* high - High Profile

This is equivalent to :
-----------------------------------
transcode_coder_type=1
transcode_enable_8x8dct=1
transcode_loop_filter=1
transcode_sc_threshold=1
transcode_x264_partitions=1
transcode_video_codec=libx264
-----------------------------------

[NOTE]
Specify different video encoding options after declaration of transcode_x264_profile may change profile to higher one. For example option "transcode_enable_8x8dct=1" will enable 8x8 transform that is supported only by High Profile.



transcode_level
~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* set level of encoding

Example values:
10 for level 1.0
11 for level 1.1
12 for level 1.2
20 for level 2.0
21 for level 2.1
30 for level 3.0
etc.



transcode_x264_partitions
~~~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* enables best use of partitions for H.264

*Possible Values:* 

* 0 - disable
* 1 - enable

Reccomended default to enable it for H.264.

FFmpeg equivalent: partitions +parti4x4+parti8x8+partp8x8+partb8x8

One of H.264's most useful features is the ability to choose among many combinations of inter and intra partitions. P-macroblocks can be subdivided into 16x8, 8x16, 8x8, 4x8, 8x4, and 4x4 partitions. B-macroblocks can be divided into 16x8, 8x16, and 8x8 partitions. I-macroblocks can be divided into 4x4 or 8x8 partitions. Analyzing more partition options improves quality at the cost of speed. The default is to analyze all partitions except p4x4 (p8x8, i8x8, i4x4, b8x8), since p4x4 is not particularly useful except at high bitrates and lower resolutions. Note that i8x8 requires 8x8dct, and is therefore a High Profile-only partition. p8x8 is the most costly, speed-wise, of the partitions, but also gives the most benefit. Generally, whenever possible, all partition types except p4x4 should be used.




transcode_loop_filter
~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* enables loop filter

*Possible Values:* 

* 0 - disable
* 1 - enable

Reccomended default to enable it for H.264.



transcode_mixed_refs
~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* one reference per partition, as opposed to one reference per macroblock

*Possible Values:* 

* 0 - disable
* 1 - enable

H.264 allows p8x8 blocks to select different references for each p8x8 block. This option allows this analysis to be done, and boosts quality with little speed impact. It should generally be used, though it obviously has no effect with only one reference frame.



transcode_enable_8x8dct
~~~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* high profile 8x8 transform (H.264)

*Possible Values:* 

* 0 - disable
* 1 - enable

Gives a notable quality boost by allowing x264 to choose between 8x8 and 4x4 frequency transform size. Required for i8x8 partitions. Speed cost for this option is near-zero both for encoding and decoding; the only reason to disable it is when one needs support on a device not compatible with High Profile.



transcode_gop
~~~~~~~~~~~~~

*Type:* <int>

*Description:* set the group of picture size

Keyframe interval, also known as GOP length. This determines the maximum distance between I-frames. Very high GOP lengths will result in slightly more efficient compression, but will make seeking in the video somewhat more difficult. For H.264 recommended default: 250.



transcode_b_frames
~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* use 'frames' B frames

B-frames are a core element of H.264 and are more efficient in H.264 than any previous standard. Some specific targets, such as HD-DVD and Blu-Ray, have limitations on the number of consecutive B-frames. Most, however, do not; as a result, there is rarely any negative effect to setting this to the maximum (16) since x264 will, if B-adapt is used, automatically choose the best number of B-frames anyways. This parameter simply serves to limit the max number of B-frames. Note that Baseline Profile, such as that used by iPods, does not support B-frames. Recommended default for H.264: 16.


transcode_mbd
~~~~~~~~~~~~~

*Type:* <int>

*Description:* macroblock decision algorithm (high quality mode)

*Possible Values:* 

* 0 - simple - use mbcmp (default)
* 1 - bits - use fewest bits
* 2 - rd - use best rate distortion

*FIXME* enables high quality mode for MPEG-4 compression.


transcode_cmp
~~~~~~~~~~~~~

*Type:* <int>

*Description:* full pel me compare function

*Possible Values:* 

* 0   - sad    - sum of absolute differences, fast (default)
* 1   - sse    - sum of squared errors
* 2   - satd   - sum of absolute Hadamard transformed differences
* 3   - dct    - sum of absolute DCT transformed differences
* 4   - psnr   - sum of squared quantization errors (avoid, low quality)
* 5   - bit    - number of bits needed for the block
* 6   - rd     - rate distortion optimal, slow
* 7   - zero   - 0
* 8   - vsad   - sum of absolute vertical differences
* 9   - vsse   - sum of squared vertical differences
* 10  - nsse   - noise preserving sum of squared differences
* 11  - w53    - 5/3 wavelet, only used in snow
* 12  - w97    - 9/7 wavelet, only used in snow
* 13  - dctmax -
* 14  - dct264 -
* 256 - chroma -

*FIXME* Used in MPEG-4 compression



transcode_subcmp
~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* sub pel me compare function

*Possible Values:* 

* 0   - sad    - sum of absolute differences, fast (default)
* 1   - sse    - sum of squared errors
* 2   - satd   - sum of absolute Hadamard transformed differences
* 3   - dct    - sum of absolute DCT transformed differences
* 4   - psnr   - sum of squared quantization errors (avoid, low quality)
* 5   - bit    - number of bits needed for the block
* 6   - rd     - rate distortion optimal, slow
* 7   - zero   - 0
* 8   - vsad   - sum of absolute vertical differences
* 9   - vsse   - sum of squared vertical differences
* 10  - nsse   - noise preserving sum of squared differences
* 11  - w53    - 5/3 wavelet, only used in snow
* 12  - w97    - 9/7 wavelet, only used in snow
* 13  - dctmax -
* 14  - dct264 -
* 256 - chroma -

*FIXME* Used in MPEG-4 compression


transcode_crf
~~~~~~~~~~~~~

*Type:* <float>

*Description:* enables constant quality mode, and selects the quality (H.264 only)

Constant quality mode (also known as constant ratefactor). Bitrate corresponds approximately to that of constant quantizer, but gives better quality overall at little speed cost. The best one-pass option in H.264.



transcode_refs
~~~~~~~~~~~~~~

*Type:* <int>

*Description:* reference frames to consider for motion compensation (H.264 only)

One of H.264's most useful features is the abillity to reference frames other than the one immediately prior to the current frame. This parameter lets one specify how many references can be used, through a maximum of 16. Increasing the number of refs increases the DPB (Decoded Picture Buffer) requirement, which means hardware playback devices will often have strict limits to the number of refs they can handle. In live-action sources, more reference have limited use beyond 4-8, but in cartoon sources up to the maximum value of 16 is often useful. More reference frames require more processing power because every frame is searched by the motion search (except when an early skip decision is made). The slowdown is especially apparent with slower motion estimation methods. Recommended default for H.264: 6.



transcode_b_strategy
~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* strategy to choose between I/P/B-frames

libx264, by default, adaptively decides through a low-resolution lookahead the best number of B-frames to use. It is possible to disable this adaptivity; this is not recommended. Recommended default for H.264: 1
0: Very fast, but not recommended. Does not work with pre-scenecut (scenecut must be off to force off b-adapt).
1: Fast, default mode in libx264. A good balance between speed and quality.
2: A much slower but more accurate B-frame decision mode that correctly detects fades and generally gives considerably better quality. Its speed gets considerably slower at high bframes values, so its recommended to keep bframes relatively low (perhaps around 3) when using this option. It also may slow down the first pass of libx264 when in threaded mode.



transcode_coder_type
~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Possible Values:* 

* 0 = vlc       variable length coder / huffman coder
* 1 = ac/CABAC  arithmetic coder
* 2 = raw       raw (no encoding)
* 3 = rle       run-length coder
* 4 = deflate   deflate-based coder

CABAC is the default entropy encoder used by x264. Though somewhat slower on both the decoding and encoding end, it offers 10-15% improved compression on live-action sources and considerably higher improvements on animated sources, especially at low bitrates. It is also required for the use of trellis quantization. Disabling CABAC may somewhat improve decoding performance, especially at high bitrates. CABAC is not allowed in Baseline Profile.



transcode_me_method
~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* set motion estimation method

*Possible Values:* 

* 1  - zero     - zero motion estimation (fastest)
* 2  - full/esa - full motion estimation (slowest)
* 3  - log      - log motion estimation
* 4  - phods    - phods motion estimation
* 5  - epzs/dia - EPZS motion estimation (default)
* 6  - x1       - X1 motion estimation
* 7  - hex      - hex motion estimation (x264 specific)
* 8  - umh      - umh motion estimation (x264 specific)
* 9  - iter     - iter motion estimation (snow specific)
* 10 - tesa     - tesa motion estimation (x264 specific)

One of the most important settings for x264, both speed and quality-wise.

epzs - is the simplest search, consisting of starting at the best predictor, checking the motion vectors at one pixel upwards, left, down, and to the right, picking the best, and repeating the process until it no longer finds any better motion vector.

hex - consists of a similar strategy, except it uses a range-2 search of 6 surrounding points, thus the name. It is considerably more efficient than DIA and hardly any slower, and therefore makes a good choice for general-use encoding.

umh - is considerably slower than HEX, but searches a complex multi-hexagon pattern in order to avoid missing harder-to-find motion vectors. Unlike HEX and DIA, the merange parameter directly controls UMH's search radius, allowing one to increase or decrease the size of the wide search.

full - is a highly optimized intelligent search of the entire motion search space within merange of the best predictor. It is mathematically equivalent to the bruteforce method of searching every single motion vector in that area, though faster. However, it is still considerably slower than UMH, with not too much benefit, so is not particularly useful for everyday encoding.



transcode_me_range
~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* limit motion vectors range

MErange controls the max range of the motion search. For HEX and DIA, this is clamped to between 4 and 16, with a recommended of 16. For UMH and ESA, it can be increased beyond the 16 to allow for a wider-range motion search, which is useful on HD footage and for high-motion footage. Note that for UMH and ESA, increasing MErange will significantly slow down encoding.



transcode_subq
~~~~~~~~~~~~~~

*Type:* <int>

*Description:* sub pel motion estimation quality

An extremely important encoding parameter for H.264 which determines what algorithms are used for both subpixel motion searching and partition decision.

1: Fastest, but extremely low quality. Should be avoided except on first pass encoding.
2-5: Progressively better and slower, 5 serves as a good medium for higher speed encoding.
6-7: 6 is the default. Activates rate-distortion optimization for partition decision. This can considerably improve efficiency, though it has a notable speed cost. 6 activates it in I/P frames, and subme7 activates it in B frames.
8-9: Activates rate-distortion refinement, which uses RDO to refine both motion vectors and intra prediction modes. Slower than subme 6, but again, more efficient.



transcode_trellis
~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* rate-distortion optimal quantization

*Possible Values:*
 
* 0 - disabled
* 1 - enabled only on the final encode of a MB
* 2 - enabled on all mode decisions

The main decision made in quantization is which coefficients to round up and which to round down. Trellis chooses the optimal rounding choices for the maximum rate-distortion score, to maximize PSNR relative to bitrate. This generally increases quality relative to bitrate by about 5% for a somewhat small speed cost. It should generally be enabled. Note that trellis requires CABAC.


transcode_sc_threshold
~~~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* scene change threshold

Adjusts the sensitivity of x264's scenecut detection. Rarely needs to be adjusted. Recommended default for H.264: 40.


transcode_rc_eq
~~~~~~~~~~~~~~~

*Type:* <string>

*Description:* set rate control equation

Ratecontrol equation. Recommended default for H.264: 'blurCplx^(1-qComp)'.



transcode_qcomp
~~~~~~~~~~~~~~~

*Type:* <float>

*Description:* video quantizer scale compression

QP curve compression: 0.0 => CBR, 1.0 => CQP. Recommended default for H.264: 0.60.


transcode_qmin
~~~~~~~~~~~~~~

*Type:* <int>

*Description:* min video quantizer scale

Minimum quantizer. Recommended default for H.264: 10.


transcode_qmax
~~~~~~~~~~~~~~

*Type:* <int>

*Description:* max video quantizer scale

Maximum quantizer. Recommended default for H.264: 51.


transcode_qdiff
~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* max difference between the quantizer scale

Set max QP step. Recommended default: 4.


transcode_keyint_min
~~~~~~~~~~~~~~~~~~~~

*Type:* <int>

*Description:* key interval