Transcode - extending the import layer

Summary

This document explain how to extend transcode to support a new format in import. This process usually involves adding support for a new codec and/or a new container. Import layer in transcode is a thick one, and involves several parts: input layer (reading the bare data from a source, usually but not exclusively a file from a filesystem), demultiplexing layer (extracting the stream data), decoding layer (transforming the encoded samples in raw data) and the probing layer (properly recognizing an encoded stream).

This document uses as much as is possible a tutorial/walk through structure. It is intended to be a guide for newcomers more than a quick reference for experienced users; neverthless, I'll do my best to be schematic, concise and direct in exposition. The u-Law format is used as rolling example; please note that all the code (and almost all examples) shown here is working and included in transcode itself.

This document assumes some basic knowledge of how transcode is structured, how multimedia processing works (colorspaces, storing data) and about the layout of transcode core data structures. The involved concepts are briefly and quickly recalled when needed, but full explanation and discussion is demanded to other, specific documents.


How import layer works

This paragraph provides an eagle-way overview of how import layer works in transcode. This will explain briefly who does what, how, when and why, informing the reader about the framework he is working within. For more detailed notes about how transcode works, see the other technical documents.

Subdividing the code

This paragraph gives some hints and suggestions about how to organize the new code that you're going to add in order to integrate nicely with existing transcode codebase. However, those are mostly hints and suggestions; mandatory requirements will be clearly made visible.

Extending the core

This paragraph highlights the changes needed to transcode core to make it fully aware of new code that you're going to add, in order to integrate it nicely and let the goodies like module hinting and autodetection work properly.

Writing the import code

This paragraph is dedicated to the real hard work, to write the new import code itself. The paragraph is structured as a walkthrough. As much as (working) sample code is used as example.

Last bits

Some final words :)


How import layer works

The way of importing

In a nutshell, the import event sequence is the following:

The probing dilemma

As highlighted in previous paragraph, probing subprocess is suboptimal for a number of reasons. First and foremost, while probing theorically belongs to import layer, and the code itself resides in import/ subdirectory, probing is not done in import modules, but by a separate process. Having probing in a separate process causes in turn a few more problems: no (easy) caching of read data, and each probed stream is open at least twice (some code paths can lead to three open()s). This is known to cause some troubles with non-file import sources like V4L. Those are known problems, mostly caused by legacy issues, and will be addressed in future releases.

Subdividing the code

body of paragraph 2

Extending the core

body of paragraph 3

Writing the import code

body of paragraph 4

Last bits

body of paragraph 5