Import_xml Documentation

Last update 2003/06/27 Marzio Malanchini <marzio_malanchini@vodafone.it>

---------------
* Index
---------------
  - Overview
  - Schema
  - Usage
  - Requierements
  - Examples
  - SMIL extract
  - Changelog
  - Todo



---------------
* Overview
---------------

The import_xml module is based on a SMIL2 directive (http://www.w3.org/2001/SMIL20/Language) and it was initially designed to manage the smil file produced by kino (http://www.schirmacher.de/arne/kino) .
Now it has some features (not supported by kino) that enable transcode to work in a different mode respect to the basic use: for example it's possible to force transcode to work with different sources in the same session (for instance only with dv, avi, mov (all mov supported by import_mov plus quicktime_dv generated by kino) or manage video sources with different height and width (for example a PAL with NTSC).


---------------
* Schema
---------------


  /---------\				/---------\
  |          |				|  load    |
  |transcode |--> autoprobe xml------->	| import   |
  |          |				|  xml     |
  \---------/				\---------/
					    |
					    | det. source
                                           \ /
					    |
				____________|________________
				|	    |		     |
				|	    |		     |
  			  /---------\   /---------\     /---------\
  			  |video.dv |   |         |     |         |
  spec. source processor  |    +    |   |video.mov|     |video.avi|
  			  |audio.avi|   |         |     |         |
  			  \---------/   \---------/     \---------/
     				\___________|_______________/
                           	            |
					   \ /
                           	            |
                     	     	     /--------------\
                     		     |internal filter|
   /---------\         		     \--------------/
   |transcode |            	            |
   |  filter  |_____________________________/
   |  module  |
   \---------/
	|
	|
   /---------\
   |  normal  |
   |transcode |
   |  flow    |
   \---------/


---------------
* Usage
---------------

import_xml module gets its options from transcode command line (such as -Q -d etc.) and from the smil file.

A simply way to use the import_xml module is to build an smil file like this:

------ start my.smil ----
<?xml version="1.0"?>
<smil xmlns:smil2="http://www.w3.org/2001/SMIL20/Language">
        <seq>
                <video src="/mnt/hd/avi/mare008.avi" clipBegin="0" clipEnd="200"/>
        </seq>
        <seq>
                <video src="/mnt/hd/avi/mare009.avi" clipBegin="smpte=00:00:10" clipEnd="20s"/>
                <audio src="/mnt/hd/avi/new-audio.avi" clipBegin="smpte=00:00:10" clipEnd="20s"/>
        </seq>
</smil>
------ end my.smil ----

and run

transcode -i my.smil -y .............

The smil file is auto probed by transcode (it's possible to force the option -x xml)

The first 2 lines define the namespace
Each sequences are include in <seq> tag and for instance is possible to define two tag <video> and <audio> .
By default audio track is taken from the <video> file but, if <audio> tag is present the module use this as audio track (the length of audio track must be the same of the video one).
Inside the <audio> and <video> tags it's possible to declare two properties: clipBegin and clipEnd: if clipBegin and/or clipEnd are not defined, all frames are processed by the input module.  The metric is conform to SMIL2 directive: see SMIL extract

All audio track can be override by pass to transcode an other smil file that specify the audio tracks.

e.g.

transcode -i my.smil -p my-audio.smil -y .............

where my-audio.smil
------ start my-audio.smil ----
<?xml version="1.0"?>
<smil xmlns:smil2="http://www.w3.org/2001/SMIL20/Language">
        <seq>
                <audio src="/mnt/hd/avi/alternative-audio.avi" clipBegin="0" clipEnd="200"/>
        </seq>
        <seq>
                <audio src="/mnt/hd/avi/alternative-audio.avi" clipBegin="201" clipEnd="550"/>
        </seq>
</smil>
------ end my-audio.smil----


In  each <audio> and <video> tag is possible to define <param> tag and this is useful to override some autoprobe parameter or activate feature

in-audio-module 		 	define the module that will be used by the import_xml module;
					only dv,mov and avi are currently supported.

in-video-module                      	define the module that will be used by the import_xml module;
					only dv,mov and avi are currently supported.

in-audio-codec                     	define the codec that will be used by the import_xml module;
					only pcm and mov related are currently supported.

in-video-codec                     	define the codec that will be used by the import_xml module;
					only yuv2 rgb yu12 yuy2 (for --dv_yuy2_mode) and raw are currently supported.

target-height				set the size of target height

target-width				set the size of target width

resize-filter				choose between bell|box|mitchell|hermite|B_spline|triangle|lanczos3 resize filter (default lanczos3)


e.g.

------ start resize.smil ----
<?xml version="1.0"?>
<smil xmlns:smil2="http://www.w3.org/2001/SMIL20/Language">
	<seq>
		<video src="/mnt/hd/avi/mare-ntsc.mov" clipBegin="0" clipEnd="100">
			<param name="in-video-codec" value="rgb"/>
		        <param name="target-width" value="352"/>
		        <param name="target-height" value="288"/>
        		<param name="resize-filter" value="mitchell"/>
		</video>
	</seq>
</smil>
------ end resize.smil ----


In one smil file it's possible to combine different video sources (PAL,NTSC) with different height and width: in that case it's necessary to declare target-height and/or target-width (or vice versa).
VERY IMPORTANT: any resize option passed from command line are ignored if target-width or target-height parameter is setting in the smil file.

It's possible to use in the same xml file different file type (i.e. avi, dv, mov...).


---------------
* Requierements
---------------

import_xml require libxml2 to be compiled in transcode (if present import_xml is enable by default)


---------------
* Examples
---------------

1) Manage different source with the same heigth and width in the same smil file (clipBegin and clipEnd in frames)

<?xml version="1.0"?>
<smil xmlns:smil2="http://www.w3.org/2001/SMIL20/Language">
	<seq>
		<video src="/mnt/hd/avi/mare-01.mov" clipBegin="0" clipEnd="100"/>
	</seq>
	<seq>
		<video src="/mnt/hd/avi/mare-02.avi" clipBegin="0" clipEnd="100"/>
	</seq>
</smil>


2) Manage different source with different heigth and width in the same smil file (clipBegin and clipEnd in different format)

<?xml version="1.0"?>
<smil xmlns:smil2="http://www.w3.org/2001/SMIL20/Language">
	<seq>
		<video src="/mnt/hd/avi/mare-01.mov" clipBegin="00:00:12" clipEnd="50s">
		        <param name="target-width" value="352"/>
		        <param name="target-height" value="288"/>
        		<param name="resize-filter" value="bell"/>
		</video>
	</seq>
	<seq>
		<video src="/mnt/hd/avi/mare-ntsc.avi" clipBegin="24" clipEnd="10s">
        		<param name="resize-filter" value="mitchell"/>
		</video>
	</seq>
</smil>


3) Override autoprobe parameter

<?xml version="1.0"?>
<smil xmlns:smil2="http://www.w3.org/2001/SMIL20/Language">
	<seq>
		<video src="/mnt/hd/avi/mare015.dv" clipBegin="10" clipEnd="60"/>
		<video src="/mnt/hd/avi/mare016.dv" clipBegin="10" clipEnd="60"/>
		<video src="/mnt/hd/avi/mare014.dv" clipBegin="10" clipEnd="60">
			<param name="in-video-module" value="dv"/>
			<param name="in-audio-module" value="dv"/>
			<param name="in-video-codec" value="rgb"/>
			<param name="in-audio-codec" value="pcm"/>
		</video>
	</seq>
</smil>


---------------
* SMIL extract
---------------


Taken from SMIL MediaClipping Module "....

Values in the clipBegin and clipEnd attribute have the following syntax:
Clip-value-MediaClipping ::= [ Metric "=" ] ( Clock-val | Smpte-val )
Metric            ::= Smpte-type | "npt"
Smpte-type        ::= "smpte" | "smpte-30-drop" | "smpte-25"
Smpte-val         ::= Hours ":" Minutes ":" Seconds
                      [ ":" Frames [ "." Subframes ]]
Hours             ::= Digit+
Minutes           ::= Digit Digit; range from 00 to 59
Seconds           ::= Digit Digit; range from 00 to 59

Frames            ::= Digit Digit; smpte range = 00-29, smpte-30-drop range = 00-29, smpte-25 range = 00-24
Subframes         ::= Digit Digit; smpte range = 00-01, smpte-30-drop range = 00-01, smpte-25 range = 00-01




SMPTE Timestamp
SMPTE time codes [SMPTE] can be used for frame-level access accuracy. The metric specifier can have the following values:

	smpte

	smpte-30-drop
	These values indicate the use of the "SMPTE 30 drop" format (approximately 29.97 frames per second), as defined in the SMPTE specification (also referred to as "NTSC drop frame").
	The "frames" field in the time value can assume the values 0 through 29. The difference between 30 and 29.97 frames per second is handled by dropping the first two frame indices
	(values 00 and 01) of every minute, except every tenth minute.

	smpte-25
	The "frames" field in the time specification can assume the values 0 through 24. This corresponds to the PAL standard as noted in [SMPTE]
	The time value has the format hours:minutes:seconds:frames.subframes. If the subframe value is zero, it may be omitted. Subframes are measured in one-hundredths of a frame.
		Examples:
		clipBegin="smpte=10:12:33:20"

Normal Play Time

	npt
	Normal Play Time expresses time in terms of SMIL clock values. The metric specifier is "npt", and the syntax of the time value is identical to the syntax of SMIL clock values.
		Examples:
		clipBegin="npt=123.45s"
		clipBegin="npt=12:05:35.3"

....."


---------------
* Changelog
---------------

2003-07-09 * docs/import-xml.txt import/import_xml.c import/ioxml.c import/af6_decore.cpp import/magic.h
- enable support for all source files readable by avifile (af6).

2003-06-26 * docs/import-xml.txt /import/import_xml.c import/ioxml.c import/ioxml.h import/Makefile.am import/probe_xml.c import/tcxmlcheck.c src/transcode.c docs/man/tcxmlcheck.1 docs/man/tcdecode.1 docs/man/transcode.1:
- change the evaluation order of audio parameter (priority: -p audio.smil, <audio> tag and then <video> tag)
- review of syncronization time for ntsc and pal
- support for source with different height and width
- adding target-height target-width and resize-filter
- document file rewritten

2003-05-30 * docs/import-xml.txt import/import_xml.c import/ioxml.c:
- enable support for libdv-yuy2.

2003-05-13 * docs/import-xml.txt import/decode_mov.c import/import_xml.c import/ioxml.c import/ioxml.h import/Makefile.am import/probe_mov.c import/probe_xml.c import/tcdecode.c import/tc.h:
- manage quicktime (as import_mov) , avi and dv file in the same xml
- manage quicktime_dv format (generated by kino not yet supported by import_mov)
- tcdecode can manage mov input file
- enable new parameters in the PARM option (see file import-xml.txt under docs directory )               `

2003-04-18 * import/ioxml.c, docs/import-xml.txt:
- allow ioxml to handle the multiple video and audio elements in the same seq statement

2003-04-09
- manage different file type in the same xml (only for dv and avi created with dvgrab/kino)
- add a program to check the consistence of xml file
- enable new parameters in the PARM option (see file import-xml.txt under docs directory )

2003-01-09
- patch for probe_xml.c
2002-06-08
- patch for import_xml.c
2002-03-27 * docs/import_xml.txt import/import_xml.c
- update for import_xml.c
2002-03-20 * first release of import_xml




---------------
* Todo
---------------

- autobuild the xml file
- extension to manage mpeg file (mpeg1,mpeg2)