= Transcoding =

A fact of life is that whatever up-to-date/shiny/expensive/... your audio/video/media player is, you'll always find some media content it can not play.[[BR]]
There are several solutions to this problems:
 * forget it (pity!),
 * retrieve the media content as a file and convert it manually (complicated!),
 * buy another device which support this type of data (expensive!),
 * or use a media server supporting transcoding.
In the last case, the media server will convert (on-the-fly or beforehand) and serve to the media player/renderer the content in a format it supports. Sounds simple, isn't it! [[BR]]


== How does it work in the UPnP world ==

Items exposes by a UPnP content directory are usually associated with one or more Resources:[[BR]]
a Resource is basically a URL, with description of the format/resolution/size/quality of the binary data which can be obtained by querying this URL.[[BR]]
 * a media server can expose and serve, for a given Item, several Resources, each of which correspond to a different version of the data 
 (original, reformatted on the fly, resized, filtered...). Then, the client chooses in the list the Resource it intends to play 
 (basically, it will take the first one on the list with a supported format, but it can be something smarter) and retrieves it from the server.
 * OR a media server can recognize the client device on the other side (thanks to informations provided within the network messages 
 and usually an internal database) and directly expose and serve a converted resource, if relevant.


== How does it work within Coherence - short story ==

not so well for the moment, but it depends on the use case... :-)

Basically, if transcoding is enabled:
  * for each audio item, coherence will expose and serve the following resources:
    * original format
    * lpcm
    * mp3
    * wav
  * for each video item, coherence will expose and server the following resources:
    * original format
    * mpeg-ts
Of course, if the original format is already lpcm/mp3/wav or mpegts, coherence won't expose two resources.

To activate transcoding, you need either use `-o transcoding:yes` on the command-line or enable it in the config file like this `<transcoding>yes</transcoding>`.

The functionnality is still highly experimental, transcoded resources may or may not work, depending on the data size or source.


== How does it work within Coherence - long story ==

Transcoding in Coherence is done by default with a GStreamer pipeline and a custom sink that writes to an http request.
So theoretically we should be able to process anything GStreamer can handle.

With [991] we got a simple transcoder for audio files. In changeset [1382] this was extended to a TranscoderManager 
that picks the matching transcoder from the internal ones or overrides via the config, global or  - not implemented yet - per backend.

Also not implemented yet is the selection of the transcoder (pipeline) per client, allowing us to serve an Nokia tablet
a different stream than a PS3.

The transcoders are still ''simple'', in terms that we can't seek in the transcoded stream yet.

The audio transcoder are tested currently against the PS3, Sony Bravia TVs and XBox 360, so far they seem to work.



Test invocation:

{{{
#!sh
bin/coherence -o transcoding:yes --plugin=backend:FSStore,content:/path/to/some/ogg-files
}}}

We need to provide several transcoders to comply with the DLNA spec or to support non-standard devices.[[BR]]
Transcoders have a '''name''' which is used to tag a Resource url so we know, - when the client is sending the http request - what format is actually requested.[[BR]]
A typical Resource url for an item does look like this:

{{{
http://host:port/12345678-c9e5-4f85-960c-8b28f384c92a/1014.m4a
}}}

The same item, with the transcoder tag has this url:

{{{
http://host:port/12345678-c9e5-4f85-960c-8b28f384c92a/1014.m4a/transcoded/lpcm
}}}

So far these transcoders are defined:

 ''lpcm'':: audio only, internally handled by a GStreamer pipeline, required by the DLNA spec
 ''mp3'':: audio only, internally handled by a GStreamer pipeline, needed for the XBox
 ''wav'':: audio only, internally handled by a GStreamer pipeline, needed for some old devices that don't understand ''lpcm'', and ogg,flac,... neither
 ''mpegts'':: internally handled by a GStreamer pipeline, required by the DLNA spec
 

Transcoders can be overwritten by a transcoder configuration fragment in the global config, and sooner or later per backend too.

Override of an internal transcoder:

{{{
#!xml
<transcoder>
  <name>lpcm</name>
  <type>gstreamer</type>
  <pipeline>%s ! decodebin ! audioconvert ! audio/x-raw-int,rate=44100,endianness=4321,channels=2,width=16,depth=16,signed=true name=mux</pipeline>
  <target>audio/L16;rate=44100;channels=2</target>
</transcoder>
}}}

Coherence can make use of transcoders that are a GStreamer pipeline or an [browser:trunk/Coherence/coherence/transcoder.py#L605 external process].


To test the MPEG2 video transcoder one might override the internal GStreamer pipeline:

{{{
#!xml
<transcoder>
  <pipeline>mpegtsmux name=mux %s ! decodebin2 name=d ! queue max-size-buffers=0 max-size-time=0 ! ffmpegcolorspace ! videorate ! mpeg2enc ! queue max-size-buffers=0 max-size-time=0 ! mux. d. ! queue max-size-buffers=0 max-size-time=0 ! audioconvert ! twolame ! queue max-size-buffers=0 max-size-time=0 ! mux.</pipeline>
  <type>gstreamer</type>
  <name>mpegts</name>
  <target>video/mpeg</target>
</transcoder>
}}}

or with an ExternalProcessPipeline:

{{{
#!xml
<transcoder>
  <pipeline>/bin/cat %s</pipeline>
  <type>process</type>
  <name>mpegts</name>
  <target>video/mpeg</target>
</transcoder>
}}}

=== Useful links: ===

 * [http://gstreamer.freedesktop.org/documentation/ GStreamer documentation]
 * [http://gstreamer.freedesktop.org/documentation/plugins.html GStreamer Plugins]
 * [http://www.cin.ufpe.br/~cinlug/wiki/index.php/Introducing_GStreamer GStreamer Introduction]
 * [http://pygstdocs.berlios.de/pygst-tutorial/pipeline.html Python GStreamer Tutorial]