1
#LyX 1.5.4 created this file. For more info see http://www.lyx.org/
10
\font_typewriter default
11
\font_default_family default
17
\paperfontsize default
25
\paperorientation portrait
32
\paragraph_separation skip
34
\quotes_language swedish
38
\tracking_changes false
47
Transcoding Content With MediaTomb
50
\begin_layout Standard
54
\begin_layout Standard
59
\begin_layout Standard
64
\begin_layout Standard
66
<holder>Gena Batsyan</holder>
69
\begin_layout Standard
71
<holder>Sergey Bostandzhyan</holder>
74
\begin_layout Standard
79
\begin_layout Standard
84
\begin_layout Standard
86
<year>2006-2008</year>
89
\begin_layout Standard
91
<holder>Gena Batsyan</holder>
94
\begin_layout Standard
96
<holder>Sergey Bostandzhyan</holder>
99
\begin_layout Standard
101
<holder>Leonhard Wimmer</holder>
104
\begin_layout Standard
114
\begin_layout Standard
118
\begin_layout Standard
120
<releaseinfo>This documentation is valid for MediaTomb version 0.12.0.</releaseinfo
129
\begin_layout Standard
133
\begin_layout Standard
143
\begin_layout Standard
144
THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK!
147
\begin_layout Standard
151
\begin_layout Standard
161
\begin_layout Section
165
\begin_layout Standard
166
MediaTomb version 0.11.0 introduces a new feature - transcoding.
167
It allows you to perform format conversion of your content on the fly allowing
168
you to view media that is otherwise not supported by your player.
172
\begin_layout Standard
173
For example, you might have your music collection stored in the OGG format,
174
but your player only supports MP3 or you have your movies stored in DivX
175
format, but your player only supports MPEG2 and MPEG4.
176
Of course you could sit down and convert everything before viewing, but
177
that is usually a time consuming procedure, besides, you often you want
178
to keep your original data untouched and end up storing both, the converted
179
and the original content - wasting space on your hard disk.
180
That's where on the fly transcoding comes into play.
183
\begin_layout Standard
184
Another use case is online content - it is often presented in flv or asf
185
formats, you may get mms or rtp streams which your player can not handle.
186
The transcoding feature makes it possible to access such content.
189
\begin_layout Standard
190
Last but not least - subtitles.
191
Only a few devices provide subtitle support, usually it's a proprietary
192
solution not covered by UPnP.
193
Using transcoding you can enable subtitles independent of the player device.
196
\begin_layout Section
200
\begin_layout Standard
201
This chapter describes the idea behind the current transcoding implementation.
204
\begin_layout Subsection
205
What Happens On The User Level
208
\begin_layout Standard
209
So how does this work? First, let's look at the normal situation where you
210
are playing content that is natively supported by your player, let's say
212
You add it to the server, browse the content on your device, hit play and
213
start streaming the content.
214
Content that the player can not handle is usually grayed out in the on
215
screen display or marked as unsupported.
218
\begin_layout Standard
219
Now, what happens if transcoding is in place?
222
\begin_layout Standard
223
First, you define transcoding profiles, specifying which formats should
224
be converted, let's assume that you have some music stored in the FLAC
225
format, but your device only supports MP3 and WAV.
226
So, you can define that all FLAC media should be transcoded to WAV.
227
You then start MediaTomb and browse the content as usual on your device,
228
if everything was set up correctly you should see that your FLAC files
229
are marked as playable now.
230
You hit play, just like usual, and you will see that your device starts
235
\begin_layout Standard
236
Here is what happens in the background: when you browse MediaTomb, we will
237
look at the transcoding profile that you specified and, assuming the example
238
above, tell your player that each FLAC file is actually a WAV file.
239
Remember, we assumed that the player is capable of playing WAV content,
240
so it will display the items as playable.
241
As soon as you press play, we will use the options defined in the transcoding
242
profile to launch the transcoder, we will feed it the original FLAC file
243
and serve the transcoded WAV output directly to your player.
244
The transcoding is done on the fly, the files are not stored on disk and
245
do not require additional disk space.
248
\begin_layout Subsection
252
\begin_layout Standard
253
The current implementation allows to plug in any application to do the transcodi
255
The only important thing is, that the application is capable of writing
256
the output to a FIFO.
257
Additionally, if the application is not capable of accessing online content
258
directly we can proxy the online data and provide a FIFO for reading.
261
\begin_layout Standard
262
The application can be any executable and is launched as a process with
263
a set of given parameters that are defined in the profile configuration.
264
The special command line tokes %in and %out that are used in the profile
265
will be substituted by the input file name or input URL and the output
269
\begin_layout Standard
270
So, the parameters tell the transcoding application: read content from this
271
file, transcode it, and write the output to this FIFO.
272
MediaTomb will read the output from the FIFO and serve the transcoded stream
273
to the player device.
276
\begin_layout Standard
277
Buffering is implemented to allow smooth playback and compensate for high
278
bitrate scenes that may require more CPU power in the transcoding process.
281
\begin_layout Standard
282
Once you press stop or once you reach end of file we will make sure that
283
the transcoding process is killed and we will clean up the FIFOs.
286
\begin_layout Standard
287
The chosen approach is extremely flexible and gives you maximum freedom
288
of choice - you can also use this framework view mms and rtp streams even
289
if this is originally not supported by your player, blend in subtitles
290
or even listen to text documents using a text to speech processor.
293
\begin_layout Description
294
Note: it is possible and may be more convenient to call a wrapper script
295
and not the transcoding application directly, however, in this case make
296
sure that your shell script uses exec when calling the transcoder.
297
Otherwise we will not be able to kill it.
300
\begin_layout Section
304
\begin_layout Standard
305
We will not go through all possible configuration tags here, they are described
306
in detail in the main documentation.
307
Instead, we will show an sample configuration and describe the creation
311
\begin_layout Standard
312
First of all you need to decide what content has to be transcoded.
313
It makes no sens to transcode something that can be played natively by
315
Next, you have to figure out how smart your device is - UPnP defines a
316
way in which it is possible to provide several resources (or several format
317
representations) of the same content, however most devices only look at
318
the first resource and ignore the rest.
319
We implemented options to overcome this, however it may get tricky if you
320
have several devices around and if each of them needs different settings.
323
\begin_layout Standard
324
All settings apply to your config.xml.
327
\begin_layout Subsection
331
\begin_layout Standard
332
What do we want to transcode? Let's assume that you have some .flv files
333
on your drive or that you want to watch YouTube videos on your device using
335
I have not yet heard of a UPnP player device that natively supports flash
336
video, so let's tell MediaTomb what we want to transcode all .flv content
337
to something that our device understands.
340
\begin_layout Standard
341
This can be done in the mimetype-profile section under transcoding, mappings:
345
<transcode mimetype="video/x-flv" using="vlcprof"/>
348
\begin_layout Standard
349
So, we told MediaTomb to transcode all video/x-flv content using the profile
351
\begin_inset Quotes sld
355
\begin_inset Quotes srd
361
\begin_layout Subsection
365
\begin_layout Standard
366
We define vlcprof in the profiles section:
370
<profile name="vlcprof" enabled="yes" type="external">
374
<mimetype>video/mpeg</mimetype>
378
<agent command="vlc" arguments="-I dummy %in --sout #transcode{venc=ffmpeg,vco
379
dec=mp2v,vb=4096,fps=25,aenc=ffmpeg,acodec=mpga,ab=192,samplerate=44100,channels
380
=2}:standard{access=file,mux=ps,dst=%out} vlc:quit"/>
384
<buffer size="10485760" chunk-size="131072" fill-size="2621440"/>
388
<accept-url>yes</accept-url>
392
<first-resource>yes</first-resource>
399
\begin_layout Standard
400
Let's have a closer look:
404
<profile name="vlcprof" enabled="yes" type="external">
407
\begin_layout Standard
408
The profile tag defines the name of the profile - in our example it's
409
\begin_inset Quotes sld
413
\begin_inset Quotes srd
416
, it allows you to quickly switch the profile on and off by setting the
418
\begin_inset Quotes sld
422
\begin_inset Quotes srd
426
\begin_inset Quotes sld
430
\begin_inset Quotes srd
433
and also defines the profile type.
434
Currently only one transcoding type is supported -
435
\begin_inset Quotes sld
439
\begin_inset Quotes srd
445
\begin_layout Subsubsection
446
Specifying The Target Mime Type
449
\begin_layout Standard
450
We need to define which mime type we are transcoding to - that's what the
451
player device will see.
452
It must be something it supports and there are also some other limitations:
453
the output format must be streamable - meaning, it must be a format which
454
can be played back without the need of seeking in the stream.
455
AVI is a good example - it contains the index at the end of the file, so
456
the player needs to seek (or use HTTP range requests) to read the index.
457
Because of that you will not be able to transcode to AVI on the fly.
458
A good target format is MPEG2 - it does not require the player to seek
459
in the stream and it can be encoded on the fly with reasonable CPU power.
462
\begin_layout Standard
463
So, let's specify our target mime type:
467
<mimetype>video/mpeg</mimetype>
470
\begin_layout Standard
471
Bear in mind that this line only tells your player device about the content
472
format, it does not tell anything to the transcoder application.
475
\begin_layout Subsubsection
476
Choosing The Transcoder
479
\begin_layout Standard
480
Now it is time to look at the agent parameter - this tells us which application
481
to execute and it also provides the necessary command line options for
486
<agent command="vlc" arguments="-I dummy %in --sout #transcode{venc=ffmpeg,vcode
487
c=mp2v,vb=4096,fps=25,aenc=ffmpeg,acodec=mpga,ab=192,samplerate=44100,channels=2
488
}:standard{access=file,mux=ps,dst=%out} vlc:quit"/>
491
\begin_layout Standard
492
In the above example the command to be executed is
493
\begin_inset Quotes sld
496
vlc, it will be called with parameter specified in the arguments attribute.
505
tokens - they are not part of the vlc command line but have a special meaning
511
token will be replaced by the input file name (i.e.
512
the file that needs to be transcoded) and the
516
token will be replaced by the output FIFO name, from where the transcoded
517
content will be read by MediaTomb and sent to the player.
520
\begin_layout Standard
521
Just to make it clearer:
525
<agent command="executable name" arguments="command line %in %out/>
528
\begin_layout Standard
529
So, an agent tag defines the command which is an executable (make sure that
530
it is in $PATH and that you have permissions to run it), and arguments
531
which are the command line options and where
539
tokens are used in the place of the input and output file names.
542
\begin_layout Description
543
Note: the output format produced by the transcoder must match the target
547
\begin_layout Subsubsection
551
\begin_layout Standard
552
There are no defaults for the buffer settings, they need to be tuned to
553
the performance of your system and also to the type of transcoded media
554
if you want to achieve the best result.
557
\begin_layout Standard
558
The idea behind buffering is the following: let's assume that you are transcodin
559
g a high quality video, the source format has a variable bitrate.
560
Your CPU can handle most scenes in real time, but occasionally some scenes
561
have a higher bitrate which require more processing power.
562
Without buffering you would not have a fluent playback - you would see
563
stuttering during those high bitrate scenes.
564
That's where buffering comes into play.
565
Before sending the data to your player for the very first time, we will
566
delay the start of the playback until the buffer is filled to a certain
568
This should give you enough slack to overcome those higher bitrate scenes
569
and watch the movie without any stuttering or dropouts.
570
Also, your CPU will not transcode the stream as fast as it is being played
572
real time), but work as fast as it can, filling up the buffer during lower
573
bitrate scenes and thus giving you the chance to overcome even long scenes
577
\begin_layout Standard
578
The buffer accepts three parameters and is defined like this:
582
<buffer size="5242880" chunk-size="102400" fill-size="1048576"/>
585
\begin_layout Standard
586
Size is the total size of the buffer, fill-size is the amount that has to
587
be filled before sending out data from the buffer for the first time.
588
Chunk-size is somewhat tricky, as you know we read the transcoded stream
589
from a FIFO, we then put it into the buffer from where it gets served to
591
We read the data from the transcoder in chunks, once we fill up the chunk
592
we put it into the buffer, so this setting is defining the size of those
594
Lower values will make the buffer feel more responsive (i.e.
595
it will be filled at a more fluent rate), however too low values will decrease
597
Also, do not set a too high value here since it may prevent smooth playback
598
- data from the buffer is being played out, if you wait for a too big chunk
599
at the same time you may empty the buffer.
602
\begin_layout Subsubsection
603
Accepting Or Proxying Online Content
606
\begin_layout Standard
607
With MediaTomb it is possible to add items that are not pointing to local
608
content, but to online resources.
609
It can be an mp3 stream, a YouTube video or some photos stored on the web.
610
In case that the online media is stored in a format that is not supported
611
by your player, you can use transcoding to convert it.
612
Some transcoding applications, like VLC, handle online content pretty well,
613
so you can give a URL directly to the transcoder and it will handle the
614
data download itself.
615
You can even use that to stream mms or rtsp streams, even if they are not
616
directly supported by your player device.
617
Some transcoders however, can not access online content directly but can
618
only work with local data.
619
For this situation we offer a special option:
623
<accept-url>no</accept-url>
626
\begin_layout Standard
627
If this option is set to
628
\begin_inset Quotes sld
632
\begin_inset Quotes srd
635
MediaTomb will handle the download of the content and will feed the input
636
to the transcoder via a FIFO.
637
Of course the transcoding application must be capable of handling input
639
This only works for the HTTP protocol, we do not handle RTSP or MMS streams,
640
use VLC is you want to handle those.
641
When this option is set to
642
\begin_inset Quotes sld
646
\begin_inset Quotes srd
649
we will give the URL to the transcoder.
652
\begin_layout Subsubsection
656
\begin_layout Standard
657
What is a resource? In this case it's the <res> tag in the XML that is being
658
sent to the player when it browses the server.
659
Each item can have one or more resources, each resource describes the type
660
of the content by specifying it's mime type and also tells the player how
661
and where to get the content.
662
So, resources within the item point to same content, but allow to present
663
it in different formats.
664
In case of transcoding we will offer the original data as well as the transcode
665
d data by using the resource tags.
666
A well implemented player will look at all resources that are available
667
for the given item and choose the one that it supports.
668
Unfortunately most players only look at the first resource and ignore the
669
rest, this feature tells us to place the transcoded resource at the first
670
position so that those renderers will see and take it.
674
<first-resource>yes</first-resource>
677
\begin_layout Subsubsection
678
Hiding Original Resource
681
\begin_layout Standard
682
Sometimes it may be required that you only present the transcoded resource
683
(read the previous section for explanation about resources) to the player.
684
This option allows to do so:
688
<hide-original-resource>yes</hide-original-resource>
691
\begin_layout Subsection
695
\begin_layout Standard
696
Sometimes you encounter a container format but want to transcode it only
697
if it has a specific codec inside.
698
Provided that MediaTomb was compiled with ffmpeg support we offer fourcc
699
based transcoding settings for AVI files.
700
A sample configuration for a profile with fourcc specific settings would
705
<avi-fourcc-list mode="ignore">
709
<fourcc>XVID</fourcc>
713
<fourcc>DX50</fourcc>
720
\begin_layout Standard
721
Please refer to the main documentation on more information regarding the
725
\begin_layout Standard
726
We also provide a way to specify that a profile should only process the
727
Theora codec if an OGG container is encountered:
731
<accept-ogg-theora>yes</accept-ogg-theora>
734
\begin_layout Standard
735
A new feature that was added in the 0.12 version possibility to specify that
736
transcoded streams should be sent out using chunked HTTP encoding.
737
This is now the default setting, since chunked encoding is preferred with
738
content where the content length is not known.
739
The setting can be controlled on a per profile basis using the following
744
<use-chunked-encoding>yes</use-chunked-encoding>
747
\begin_layout Section
748
Testing And Troubleshooting
751
\begin_layout Standard
752
The external transcoding feature is very flexible, however there is a price
753
for flexibility: a lot of things can go wrong.
754
This section will try to cover the most common problems and present some
755
methods on how things can be tested outside of MediaTomb.
758
\begin_layout Subsection
759
Testing The Transcoder
762
\begin_layout Standard
763
It's a good idea to test your transcoding application before putting together
765
As described in the previous sections we get the transcoded stream via
766
a FIFO, so it's important that the transcoder is capable of writing the
768
This can be easily tested in the Linux command prompt.
771
\begin_layout Standard
772
Open a terminal and issue the following command:
779
\begin_layout Standard
780
This will create a FIFO called tr-test in the /tmp directory.
781
Open a second terminal, we will use one terminal to run the transcoder,
782
and another one to examine the output.
785
\begin_layout Standard
786
For this test we will assume that we want to transcode an OGG file to WAV,
787
the easiest way to do so is to use the ogg123 program which is part of
788
the vorbis-tools package.
789
Running ogg123 with the -d wav -f outfile parameter is exactly what we
790
want, just remember that our outfile is the FIFO.
791
So, run the following command, replacing some audio file with an OGG file
792
that is available on your system, in one of the terminals:
796
ogg123 -d wav -f /tmp/tr-test /some/audio/file.ogg
799
\begin_layout Standard
800
The program will start and will appear to be hanging - it's blocked because
801
noone is reading from the FIFO.
802
While ogg123 is hanging, go to the second terminal and try playing directly
803
from the FIFO (in this example we will use VLC to do that):
810
\begin_layout Standard
811
If all goes well you should see that ogg123 is coming to life and you should
812
hear the output from VLC - it should play the transcoded WAV stream.
815
\begin_layout Subsection
819
\begin_layout Standard
820
This section will try to cover the most common problems related to the external
824
\begin_layout Subsubsection
828
\begin_layout Standard
829
What if the resulting stream is unplayable?
832
\begin_layout Standard
833
This can be the case with some media formats and contaeinrs.
834
A good example is the AVI container - it contains the index at the very
835
end of the file, meaning, that a player needs to seek to the end to get
836
the index before rendering the video.
837
Since seeking is not possible in transcoded streams you will not be able
838
to transcode something to AVI and watch it from the FIFO.
841
\begin_layout Subsubsection
842
Transcoding Does Not Start
845
\begin_layout Standard
846
As explained in the previous sections, transcoding only starts when your
847
player issues an HTTP GET request to the server.
848
Further, the request must be made to the transcoding URL.
851
\begin_layout Standard
852
Most common cases are:
855
\begin_layout Standard
859
\begin_layout Standard
861
<itemizedlist><listitem>
869
\begin_layout Standard
870
wrong mime type mapping: are you sure that you specified the source mime
871
type correctly? Recheck the settings in the <mimetype-profile> section.
872
If you are not sure about the source mime type of your media you can always
873
check that via the web UI - just pick one of the files in question and
874
click on the Edit icon.
877
\begin_layout Standard
881
\begin_layout Standard
883
</listitem><listitem>
891
\begin_layout Standard
892
wrong output mime type: make sure that the mime type specified in the profile
893
matches the media format that is produced by your transcoder.
896
\begin_layout Standard
900
\begin_layout Standard
902
</listitem><listitem>
910
\begin_layout Standard
911
no permissions to execute the transcoding application: check that the user
912
under which MediaTomb is running has sufficient permissions to run the
913
transcoding script or application.
916
\begin_layout Standard
920
\begin_layout Standard
922
</listitem><listitem>
930
\begin_layout Standard
931
transcoding script is not executable or is not in $PATH: if you use a wrapper
932
script around your transcoder, make sure that it is executable and can
933
be found in $PATH (unless you specified an absolute name)
936
\begin_layout Standard
940
\begin_layout Standard
942
</listitem></itemizedlist>
950
\begin_layout Subsubsection
951
Problem Transcoding Online Streams
954
\begin_layout Standard
955
Some transcoding applications do not accept online content directly or have
956
problems transcoding online media.
957
If this is the case, set the <accept-url> option appropriately (currently
958
MediaTomb only supports proxying of HTTP streams).
959
This will put the transcoder between two FIFOs, the online content will
960
be downloaded by MediaTomb and fed to the transcoder via a FIFO.
added
removed
doc/transcoding.lyx
