ITVC architecture
m |
|||
| Line 1: | Line 1: | ||
| + | ''Note: development of ITVC has stopped. There are [[Video encoding | many popular community-maintained alternatives]] for transcoding - for example [[Video encoding #tablet-encode |tablet-encode]]'' | ||
| + | |||
==Introduction== | ==Introduction== | ||
Revision as of 17:18, 2 February 2010
Note: development of ITVC has stopped. There are many popular community-maintained alternatives for transcoding - for example tablet-encode
Contents |
Introduction
The Internet Tablet Video Converter (from now on called ITVC) application is composed of two main components. The UI takes care of only the user interface and high level business logic, it does not process, or even handle, media files directly. This job is working with media files is delegated to a Media Handler process. This approach removes the burden of dealing with the universe of codecs and media conversion from the UI portion of the app and leaving it free to specialize in what it does best: top notch user interface and usability. This architecture also enables ITVC to use different multimedia frameworks seamlessly by isolating them in a completely independent process: the Media Handler.
But all that wouldn't mean much if the communication between ITVC and Media Handler was complicated and hard to implement. Thus the communication is done using simple XML-like elements via TCP sockets. Easy to debug, parse and implement.
This simple and modular architecture also opens the door for third-party developers to easily make their own Media Handlers.
This document describes how ITVC and a Media Handler interact. This is all that one needs to know to be able to develop a Media Handler or to write their own code to interface to it.
Overview
The Media Handler acts as a server listening for TCP connections on a given port. The GUI front end then opens one or more simultaneous client sockets to the Media Handler port and exchanges data in a 2-way communication
The Media Handler is launched by the main ITVC application, which reads the mhstarter.cfg file (in its main installation directory) to determine which application to actually launch.
You can start the built-in Media Handler provided by ITVC by launching it manually outside of the main application. To do this, simply open up a command line terminal and change directory to the place where the ITVC app was installed. The port to be listened to by the Media Handler is given as a parameter when launching it. The following command line command, for instance, will open a Media Handler using port 1234:
$> ./mediahandler 1234
Executing the Media Handler without specifying the port is considered to be an error.
There can be only one instance of a Media Handler implementation running at any given time. So when a Media Handler is started it should check whether there's already another instance of itself (regardless of the port being used) running and if that's the case it should quit (leaving the existing one untouched). Please note this design principle if you decide to implement your own Media Handler.
ITVC will maintain a separate idle connection to the Media Handler with the sole purpose of checking whether the Media Handler process is still running. Communication Protocol
All communication is done using commands from the ITVC to a Media Handler. The data transfered is XML-like elements using regular ASCII characters for the tags. They are XML-like elements instead of regular XML because their format is very limited and strict in order to make the implementation of a command parser as simple as possible. No whitespaces is allowed inside or between the tags. All commands follows this syntax:
<command-name>param1|param2|param3|...</command-name>
Where command-name is the name of the command that is being issued and paramN is the command's Nth parameter. Parameters are separated by a vertical bar "|". For example: Every single byte between "<command-name>" and the first "|" is considered to be the first parameter.
All defined command names and parameter values are case sensitive (they should be lower case, more specifically).
If a command has no parameters, it will look like the following:
<command-name></command-name>
The collapsed format is not supported, so the following is invalid:
<command-name/>
When the execution of a command has finished, Media Handler replies with:
<result>value</result>
Where value is the result value. If a command succeeds, Media Handler will return the following ASCII string to ITVC:
<result>ok</result>
The result value "ok" means a successful command execution. Any value different than that means an error. An error result should be a terse english sentence in ASCII. When possible, a Media Handler should try to use one of the defined error messages.
| Error message | Description |
|---|---|
| unknown command | The command issued by ITVC is not known. |
| invalid parameters | If Media Handler fails to parse or recognize one or more parameters of a command. |
| command failed | Media Handler received a known command, with apparently valid parameters, but its execution failed. |
| aborted | If the command was aborted during its execution. |
The communication that can happen between ITVC issuing a command and Media Handler replying the result varies according to the command that has been issued.
Commands
A Media Handler has the following commands:
fetch-info
Gathers information from the specified media file and, optionally, creates a thumbnail of it.
Parameters: 1. Media's full file path. 2. Optional. Full file path of the thumbnail to be generated.
Example:
<fetch-info>/Users/foo/myvideo.mov|/Users/foo/myvideo_thumbnail.png</fetch-info>
Before sending the command result element, Media Handler will send one or more media properties complying with the following format:
<name>value</name>
Where name and value are set according to the following table:
| name | value |
|---|---|
| video-codec | Video codec name. |
| audio-codec | Audio code name. |
| fps | Frames per second. A positive integer. |
| width | Width in pixels. A positive integer. |
| height | Height in pixels. A positive integer. |
| length | Media duration in seconds. A positive integer. |
| file-size | File size in bytes. A positive integer. |
| video-bit-rate | Video bit rate (per second). A positive integer. |
Example session:
ITVC -> Media Handler:
<fetch-info>/Users/foo/myvideo.mov|/Users/foo/myvideo_thumbnail.png</fetch-info>
Media Handler -> ITVC:
<audio-codec>Ogg Vorbis</audio-codec>
Media Handler -> ITVC:
<length>182</length>
Media Handler -> ITVC:
<file-size>3072</file-size>
Media Handler -> ITVC:
<result>ok</result>
transcode
Converts the specified media file according to the given parameters saving the resulting file at the specified file path.
Parameters: 1. Input path. Full file path of the media that's going to be converted. 2. Output path. Full file path of the conversion result. 3. Width, in pixels, of the converted media file. 4. Height, in pixels, of the converted media file. 5. Preferred video compression technology. 6. Video data rate, in bits per second. 7. Audio data rate, in bits per second. 8. Video refresh rate, in frames per second.
If the video encoder specified in the fifth parameter is not available (or cannot be used for some reason), the Media Handler may fallback to a more convenient one without returning any error or specific feedback. This fallback action is considered a normal (although undesired) behavior.
The table below defines the valid values (along with their respective meanings) for the video compression parameter:
| Value | Description |
|---|---|
| mpeg4 | MPEG-4 Part 2, Advanced Simple Profile (ASP) |
| h.264 | MPEG-4 Part 10, either Main or High Profile |
| theora | Theora, from Xiph.org Foundation[1] |
- ↑ Note that the default codecs shipped with the ITVC do not support Theora as an output format. This parameter is there as a placeholder should a 3rd party developer actually implement Theora encoding in new codecs.
Example:
<transcode>C:\temp\myvideo.wmv|C:\temp\myconvertedvideo.mp4|400|240|mpeg4|350000|128000|24</transcode>
During the conversion, Media Handler will inform ITVC about the conversion progress by sending progress messsages at arbitrary time intervals. Those messages have the following format:
<progress>number</progress>
Where number is a positive integer from 0 (inclusive, meaning 0% done) to 10000 (inclusive, meaning 100% done).
When Media Handler sends a progress status message, it waits for a response from ITVC on whether it should continue converting or promptly abort the conversion. The progress reply from ITVC has the following format:
<progress-reply>value</progress-reply>
Where value can be either "proceed", meaning that Media Handler should proceed with the conversion, or "abort", meaning that the conversion should stop at once.
Example session:
ITVC -> Media Handler:
<transcode>C:\temp\myvideo.wmv|C:\temp\myconvertedvideo.mp4|400|240|mpeg4|350000|128000|24</transcode>
Media Handler -> ITVC:
<progress>204</progress>
ITVC -> Media Handler:
<progress-reply>proceed</progress-reply>
Media Handler -> ITVC:
<progress>510</progress>
ITVC -> Media Handler:
<progress-reply>proceed</progress-reply>
Media Handler -> ITVC:
<progress>948</progress>
ITVC -> Media Handler:
<progress-reply>proceed</progress-reply>
Media Handler -> ITVC:
<progress>1159</progress>
ITVC -> Media Handler:
<progress-reply>abort</progress-reply>
Media Handler -> ITVC:
<result>aborted</result>
quit
Makes Media Handler's process exit.
Example:
<quit></quit>
Here's a visual representation of the interaction process between the ITVC GUI and the Media Handler process based on the above protocol.
