DivXMux Command Line Reference Release Date: November 28, 2005
DivXMux Command Line Reference
Table of Contents
Table of Contents Table of Contents ....................................................................................................................... i Document License ......................................................................................................................ii 1 Introduction ........................................................................................................................ 1 2 DivX Media Format Features ............................................................................................... 2 3 Construction Process........................................................................................................... 4 3.1 Titles............................................................................................................................. 5 3.2 Menus ......................................................................................................................... 11 4 Internationalization .......................................................................................................... 12 4.1 Language Codes........................................................................................................... 12 4.2 Country Codes ............................................................................................................. 15
DivX, Inc.
Page i
DivXMux Command Line Reference
Document License
Document License NO COMMERCIAL USE: This License Agreement grants you the right to use the Software/Documentation for personal use only. The License Agreement grants you the right to use the Software in order to evaluate and provide feedback about it to DivX, Inc. Commercial use of the Software/Documentation or of the work products resulting from its use is not permitted under this License Agreement.
DivX, Inc.
Page ii
DivXMux Command Line Reference
1 Introduction DivXMux is the “Swiss Army Knife” of DivX tools. It performs all the necessary file preparation and assembly required to construct DivX files, including DivX Media Format features; alternate audio tracks, multiple subtitle tracks, metadata, multiple titles, chapter points, and interactive menus.
DivX, Inc.
Page 1
DivXMux Command Line Reference
2 DivX Media Format Features Listed below is the feature set from the DivX Media Format: • Multiple titles o
Each title may be a full- length feature, special features, an episode, or any other piece of media content.
o
Titles do not have to use the same video resolution or audio format as the main feature.
o
Maximum of 100 titles.
• Chapter points o
Each chapter point has a label associated with it. This is useful when a file has no menu, or the menu is not in play.
o
Chapter points are defined by start and end time stamps.
o
Maximum of 100 chapters points per title.
• Alternate audio tracks o
Maximum of 8 per title.
o
Supports MPEG 1/2 Layer 3 (MP3), Dolby Digital (AC3), MPEG 1/2 Layer 2 (MP2) audio formats.
• Multiple subtitle tracks o
Maximum of 8 per title.
o
Maximum of 3 colours per track.
• Metadata The metadata is limited to the first title in the file, and not following titles. The following table lists and describes the supported metadata fields: Field Title Type Copyright License Encoded By Website Genre Publisher Cast/Creators
DivX, Inc.
Description Title of the Content Movie, Series Rights Person who encoded the file Persons Website The genre of the content The studio that published the content Content Cast
Page 2
DivXMux Command Line Reference
Encoder Version Codec Name Codec Version CLI settings
Name and Version of the Encoding Application Name of the codec used for the track Name and Version of the Codec Used Command Line flags and options
Quantizer Distribution - per pass
Q1-Q32 Integers per pass (max 3 passes)
Frame Type Distribution - per pass Frame Period Resolution Pixel Aspect Ratio Source Input Runtime Certification
I,B,P,S Integers per pass (max 3 passes) Rate x Scale Width x Height x Frame Rate Par Height, Par Width Original Source Format (DV, MPEG-2, CAPTURE, TV) Runtime length in seconds DivX Certification
• Interactive menus o
Interactive menus contain background video, with optional audio, and buttons. Each button is a specified region on the background video, with an accompanying highlight. The highlight is an overlay is supports a maximum of 3 colours, and is displayed when the button is selected.
o
Supports transitions into menus and titles. Transitions are video, with optional audio, which is played before a menu or title appears.
o
Supports switching a title’s active audio or subtitle track on button selection.
o
Supports playing a title, a playing a title from a chapter point, entering a menu or transition on button selection.
o
Maximum of 1000 menus, each with a maximum of 100 buttons.
Note: At this time the DivX Media Format is only available in Home Theatre resolutions, and not High Definition resolutions.
DivX, Inc.
Page 3
DivXMux Command Line Reference
3 Construction Process With the introduction of the DivX Media Format feature sets, DivX files are no longer thought of as just linear video. We introduce two new concepts when talking about DivX files; titles and menus. A title is a continuous piece of content, such as a movie or sports game. A title contains multiple media streams, one video stream being mandatory, with an optional (up to 8) audio and subtitle streams. Every DivX file without the DivX Media Format can be considered a title. It is important to keep the meaning of a “title” in mind when working with DivX files. Menus involve an interactive experience, with multiple menu screens and buttons which perform actions such as transitioning to other menus, switching audio and subtitle tracks on titles, and initiating playback of titles. Below is a high level look at the construction flow between media files, the DivXMux, and the output DivX file.
video DivXMux audio DivX file subtitle XML
The output from DivXMux is always a single DivX file, although the purpose of this file is dependent on the construction process. The following command line option is used to specify the location of the output DivX file: --outfile
DivX, Inc.
Page 4
DivXMux Command Line Reference
is the relative or full path to the output DivX file. If the path does not end in the “.divx” extension the “.divx” extension will be appended. The following sections will explain in more detail the process of constructing the two distinct types of DivX files.
3.1 Titles Since titles are simply a collection of synchronized streams which make up a linear playback experience, they are fairly simply to construct. The process involves providing several media streams to DivXMux, waiting for it to perform the construction process, which results in a DivX file. 3.1.1
Video
The following command line option is used to specify a video input source file to be included in the title being constructed: --video [(strn data)] is the relative or full path to the input file. Valid input file types are *.divx and *.avi, with one of the following fourCCs; ‘DIVX’, ‘DX50’, or ‘XVID’. The optional field (strn data) is a string used to tag the stream with metadata which describes the stream’s language, country of origin, and content type. See section 3.1.5 DivX Stream Name Information — ‘strn’ for details. 3.1.2
Audio
The following command line option is used to specify an audio input source file to be included in the title being constructed: --audio [(strn data)] [#] [o] is the relative or full path to the input file. Valid input file types are *.divx, *.avi, *.mp3, and *.ac3. The optional field (strn data) is a string used to tag the stream with metadata which describes the stream’s language, country of origin, and content type. See section 3.1.5 DivX Stream Name Information — ‘strn’ for details. The optional field # specifies the audio track number from the *.divx or *.avi input source file to be included in the title being constructed. The number is relative to the number of audio tracks in the
DivX, Inc.
Page 5
DivXMux Command Line Reference
file. For example, a *.divx file contains 1 video track, 3 audio tracks, and 1 subtitle track for a total of 5 tracks. The valid audio track numbers are 1, 2, and 3. The optional field o specifies the amount of offset, in milliseconds, to apply to the input source audio. Negative values are accepted. 3.1.3
Subtitle
The following command line option is used to specify a subtitle input source file to be included in the title being constructed: --subtitle [(strn data)] [#] --audio [(strn data)] [#] [o]
is the relative or full path to the input file. Valid input file types are *.divx, *.avi, *.srt (SubRip), *.idx, *.txt (DivX Subtitle Linker Text file). See section 3.1.6 DivX Subtitle Linker Text File for details. The optional field (strn data) is a string used to tag the stream with metadata which describes the stream’s language, country of origin, and content type. See section 3.1.5 DivX Stream Name Information — ‘strn’ for details. The optional field # specifies the subtitle track number from the *.divx or *.avi input source file to be included in the title being constructed. The number is relative to the number of subtitle tracks in the file. For example, a *.divx file contains 1 video track, 3 audio tracks, and 1 subtitle track for a total of 5 tracks. The valid subtitle track number is 1. 3.1.4
Menu Building Blocks
The following command line option specifies the output file will be used to hold the tracks for a menu. These files are temporary building blocks for interactive menus, and are referenced by the XML configuration file (--xml option). These files are not compatible with playback devices or software. These files require one video track, and support an optional audio and subtitle track. --menumode --audio [(strn data)] [#] [o ]
3.1.5
DivX Stream Name Information — ‘strn’
The DivX Stream Name information is a string which describes a video, audio, or subtitle stream’s content type, language and associated country.
Video and audio streams do not require a valid string, however subtitle streams require a valid string. The syntax is as follows: “streamType [– [languageTag[-countryTag]];typeTag]” Items inside square brackets are optional.
3.1.5.1 streamType streamType identifies the stream’s content type. The following are valid values:
DivX, Inc.
Page 6
DivXMux Command Line Reference
•
Video
•
Audio
•
Subtitle
3.1.5.2
languageTag
languageTag identifies the language of the stream’s content. It is a case-insensitive 2 character language code as specified in section 4.1 Language Codes. As shown in the syntax, the languageTag is optional. Each language code has an associated string which contains the full name of the language it represents. If langaugeTag is present, then the corresponding language should be displayed on screen. This would typically occur when switching audio and subtitle tracks, or displaying detailed track information. When possible, the language should be localized to the locale of the playback device for an improved user experience. If a languageTag is not provided, or the languageTag provided does not correspond to a known or defined language then nothing is displayed.
3.1.5.3
countryTag
countryTag identifies the country of the stream’s content. It is a case-insensitive 2 character country code as specified in section 4.2 Country Codes. As shown in the syntax, the countryTag is optional. It is only permitted if languageTag is present. Each country code has an associated string which contains the full name of the country it represents. If desired, the corresponding country could be displayed on screen for an improved user experience, however the display of country information is not required. Display would typically occur when switching audio and subtitle tracks, or displaying detailed track information. When possible, the country should be localized to the locale of the playback device for an improved user experience. If a countryTag is not provided, or the countryTag provided does not correspond to a known or defined country then nothing is displayed.
3.1.5.4
typeTag
typeTag identifies the content type for the stream. They are case-insensitive 2 character codes which are unique for each streamType. For the streamType of “Video” the following are the identifiers and their corresponding description: Codes CO HV MO MT MV TS VC
Video Types Description Commercial Home Video Movie Movie Trailer Music Video Television Show Video Clip
For the streamType of “Audio” the following are the identifiers and their corresponding description:
DivX, Inc.
Page 7
DivXMux Command Line Reference
Codes 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17
Audio Type Description Other Primary Feature Director Commentary Writer Commentary Producer Commentary Cast Commentary Critic Commentary Score Commentary Production Designer Commentary Special Effects Commentary Fan Commentary Other Commentary Isolated Score Soundtrack Interview For Visually Impaired Alternative Director Commentary
For the streamType of “Subtitle” the following are the identifiers and their corresponding description: Code 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17
3.1.6
Subtitle Type Description Other Normal Letterbox Wide Screen Full Screen Closed Captioned Forced Karaoke Not Specified Large Children Director Commentary Large Director Commentary Director Commentary for Children Normal Captions Large Captions Children's Captions
DivX Subtitle Linker Text File
The DivX Subtitle Linker Text file is used to reference bitmap (.bmp) files which make up a subtitle stream. The file also includes subtitle display start and end timestamps, positioning information, and
DivX, Inc.
Page 8
DivXMux Command Line Reference
colour palette. The file is used when making menu building blocks with the –menumode command line option. The bitmap (.bmp) files referenced by the file must have the following qualities: •
For menus, the resolution (width and height in pixels) must match the resolution of the video used for that menu.
•
For titles, the resolution must be 640 x 480 or less.
•
The width (in pixels) must be a multiple of two.
•
The height (in pixels) must be a multiple of two.
•
It must use 4 bits per pixels. This means the bitmap uses a color lookup table of 16 colors.
•
The pixels in the bitmap must only use the first 4 colors in the index table.
It must be noted how the colors used in the bitmap relate to the colors used when the subtitle is displayed. The input bitmap uses 4 bits per pixel, which means there is the possibility of 16 colors. DivX subtitles only support 3 colors, and care must be taken to ensure only the first 4 colors in the bitmap’s color lookup table are used. The first color is used to identify the pixels which are to be transparent when displayed, and the following 3 are opaque, not blended with the video, and are displayed in full. The following is an example of a bitmap:
Pattern 1 Pattern 2 Pattern 3 And the corresponding bitmap’s colour lookup table:
Color Index 0
DivX, Inc.
1
2
3
4
5
6
7
8 9 10 11 12 13 14 15
Page 9
DivXMux Command Line Reference
Any pixel which uses a color outside the first four in the color lookup table will be ignored. The colors specified in the color lookup table are not the colors used when the subtitle is displayed. The display colors are specified separately, as shown below.
The DivX Subtitle Linker Text file’s syntax is as follows: 0 1 2 3
= = = =
(0,0,0) (Red1,Green1,Blue1) (Red2,Green2,Blue2) (Red3,Green3,Blue3)
SUBPALETTE (0 1 2 3) HH2:MM2:SS2.XXX2 HH1:MM1:SS1.XXX1
"file.bmp"1 (Left1 Top1 Right1 Bottom1)
Where: Symbol
Definition
0
Reserved.
1
The RGB value of a pattern pixel in the bitmaps. Pixels in the bitmap which use the second color in the color lookup table will use this color when displayed.
2
The RGB value of a pattern pixel in the bitmaps. Pixels in the bitmap which use the third color in the color lookup table will use this color when displayed.
3
The RGB value of a pattern pixel in the bitmaps. Pixels in the bitmap which use the fourth color in the color lookup table will use this color when displayed.
Redn
The pixel’s red channel value. Valid values range 0 to 255.
Greenn
The pixel’s green channel value. Valid values range 0 to 255.
Bluen
The pixel’s blue channel value. Valid values range 0 to 255.
HH1:MM1:SS1.XXX
The time for when the subtitle should be displayed. Where HH1 is hours, MM1 is minutes, SS1 is seconds, and XXX1 is milliseconds. The time is relative to the video stream.
1
When used for menus these values are irrelevant and ignored. HH2:MM2:SS2.XXX 2
The time for when the subtitle should be cleared. Where HH2 is hours, MM2 is minutes, SS2 is seconds, and XXX2 is milliseconds. The time is relative to the video stream. When used for menus these values are irrelevant and ignored.
"file.bmp"1
DivX, Inc.
The relative or full pathname to the bitmap (.bmp) file.
Page 10
DivXMux Command Line Reference
Left1
The position in the available subtitle window, where the subtitle’s left edge is located. For menus this value must be 0.
Top1
The position in the available subtitle window, where the subtitle’s top edge is located. For menus this value must be 0.
Right1
The position in the available subtitle window, where the subtitle’s right edge is located. This value is the width of the subtitle minus, ie. Right1 = (width – 1).
Bottom1
The position in the available subtitle window, where the subtitle’s bottom edge is located. This value is the height of the subtitle minus one, ie. Bottom1 = (height – 1).
When generating subtitles overscan must be considered. Most televisions have overscan (resulting in only 80-90% of the video frame being displayed). Some combinations of display and decoding devices may display the entire video image; others may crop the border of the video. For DivX the safe viewing area is 6.7% from the left, 6.7% from the right, 5% from the top, and 5% from the bottom. The number of pixels is rounded up to the next even number. The following table shows the safe viewing area dimension and position: Dimension Certification Profile Portable Home Theater
Position
Width
Height
Left
Top
Right
Bottom
552
432
44
24
595
455
The DivXMux will enforce these rules on all subtitles. For optimal quality, subtitles should respect the safe viewing area before feed into the DivXMux.
3.2 Menus The menu construction process is based around the interpretation of an XML configuration file which details the menu structure and references the temporary menu building blocks and titles needed. The temporary menu building blocks are constructed using the –menumode command line option, each one represents an individual menu screen. The following command line option is used to specify the location of the XML configuration file: --xml is the relative or full path to the XML configuration file. Please refer to the DivX Media
Format XML Reference for details on the XML configuration file specification.
The following command line option is used to specify the location of the temporary direction to be used for temporary files generated in the menu construction process:
DivX, Inc.
Page 11
DivXMux Command Line Reference
--temp is a full path to the temporary directory. 3.2.1
Menus Resolutions
Menus are supported in the following range of resolutions: •
4:3 aspect ratio - 320 x 240 to 640 x 480.
•
16:9 aspect ratio – 320 x 180 to 720 x 404.
Menus can be of any resolution between the minimum and maximum supported resolutions stated above for both 4:3 and 16:9 aspect ratios. Both the width and heights must be multiples of 4.
4 Internationalization DivX technology is language and country agnostic and not specific to any region – it embraces the true value of electronic delivery and IP-based networks (ie. the Internet). Language and country codes are a form of metadata used to customize the viewing experience to the native language of the viewer, including interactive menuing and multiple tracks. For example, when switching audio tracks the description of the track is shown on screen in the native language of the viewer.
4.1 Language Codes Language codes are two-letter codes for the representation of names of languages. The codes cover most of the major languages of the world that are not only mostly frequently represented in the total body of the world’s literature, but which also comprise a considerable volume of specialized languages and terminologies. The codes below are devised from ISO 639:1988 – Code for the representation of names of languages. The codes are not case-sensitive. There are 136 supported language codes. The recommended use of the language codes is in lower case, but they should be considered case-insensitive and are unique codes regardless of case. The localization of the language code description is allowed and recommended.
Code aa ab af am ar as ay az ba be
DivX, Inc.
English Description Afar Abkhazian Afrikaans Amharic Arabic Assamese Aymara Azerbaijani Bashkir Byelorussian
Page 12
DivXMux Command Line Reference
bg bh bi bn bo br ca co cs cy da de dz el en eo es et eu fa fi fj fo fr fy ga gd gl gn gu ha hi hr hu hy ia ie ik in is it iw ja ji jw ka kk kl
DivX, Inc.
Bulgarian Bihari Bislama Bengali Tibetan Breton Catalan Corsican Czech Welsh Danish German Bhutani Greek English Esperanto Spanish Estonian Basque Persian Finnish Fiji Faeroese French Frisian Irish Gaelic Galician Guarani Gujarati Hausa Hindi Croatian Hungarian Armenian Interlingua Interlingue Inupiak Indonesian Icelandic Italian Hebrew Japanese Yiddish Javanese Georgian Kazakh Greenlandic
Page 13
DivXMux Command Line Reference
km kn ko ks ku ky la ln lo lt lv mg mi mk ml mn mo mr ms mt my na ne nl no oc om or pa pl ps pt qu rm rn ro ru rw sa sd sg sh si sk sl sm sn so
DivX, Inc.
Cambodian Kannada Korean Kashmiri Kurdish Kirghiz Latin Lingala Laothian Lithuanian Latvian Malagasy Maori Macedonian Malayalam Mongolian Moldavian Marathi Malay Maltese Burmese Nauru Nepali Dutch Norwegian Occitan Oromo Oriya Punjabi Polish PashtoPushto Portuguese Quechua Rhaeto-Romance Kirundi Romanian Russian Kinyarwanda Sanskrit Sindhi Sangro Serbo-Croatian Singhalese Slovak Slovenian Samoan Shona Somali
Page 14
DivXMux Command Line Reference
sq sr ss st su sv sw ta te tg th ti tk tl tn to tr ts tt tw uk ur uz vi vo wo xh yo zh zu
Albanian Serbian Siswati Sesotho Sudanese Swedish Swahili Tamil Tegulu Tajik Thai Tigrinya Turkmen Tagalog Setswana Tonga Turkish Tsonga Tatar Twi Ukrainian Urdu Uzbek Vietnamese Volapuk Wolof Xhosa Yoruba Chinese Zulu
4.2 Country Codes Country codes are two-letter codes for the representation of names of countries. The codes below are devised from ISO 3166:1988 – Code for the representation of countries and their subdivisions. The codes are not case-sensitive. There are 240 supported country codes. The recommended use of the country codes is in upper case, but they should be considered case-insensitive and are unique codes regardless of case. The localization of the country code description is allowed and recommended.
Code AF AX
DivX, Inc.
English Description Afghanistan Åland Islands
Page 15
DivXMux Command Line Reference
AL DZ AS AD AO AI AQ AG AR AM AW AU AT AZ BS BH BD BB BY BE BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI KH CM CA CV KY CF TD CL CN CX CC CO KM CG
DivX, Inc.
Albania Algeria American Samoa Andorra Angola Anguilla Antarctica Antigua and Barbuda Argentina Armenia Aruba Australia Austria Azerbaijan Bahamas Bahrain Bangladesh Barbados Belarus Belgium Belize Benin Bermuda Bhutan Bolivia Bosnia and Herzegovina Botswana Bouvet Island Brazil British Indian Ocean Territory Brunei Darussalam Bulgaria Burkina Faso Burundi Cambodia Cameroon Canada Cape Verde Cayman Islands Central African Republic Chad Chile China Christmas Island Cocos (Keeling) Islands Colombia Comoros Congo
Page 16
DivXMux Command Line Reference
CD CK CR CI HR CU CY CZ DK DJ DM DO EC EG SV GQ ER EE ET FK FO FJ FI FR GF PF TF GA GM GE DE GH GI GR GL GD GP GU GT GN GW GY HT HM VA HN HK HU
DivX, Inc.
The Democratic Republic of the Congo Cook Islands Costa Rica Cote D'ivoire Croatia Cuba Cyprus Czech Republic Denmark Djibouti Dominica Dominican Republic Ecuador Egypt El Salvador Equatorial Guinea Eritrea Estonia Ethiopia Falkland Islands (Malvinas) Faroe Islands Fiji Finland France French Guiana French Polynesia French Southern Territories Gabon Gambia Georgia Germany Ghana Gibraltar Greece Greenland Grenada Guadeloupe Guam Guatemala Guinea Guinea-Bissau Guyana Haiti Heard Island and McDonald Islands Holy See (Vatican City State) Honduras Hong Kong Hungary
Page 17
DivXMux Command Line Reference
IS IN ID IR IQ IE IL IT JM JP JO KZ KE KI KP KR KW KG LA LV LB LS LR LY LI LT LU MO MK MG MW MY MV ML MT MH MQ MR MU YT MX FM MD MC MN MS MA MZ
DivX, Inc.
Iceland India Indonesia Islamic Republic of Iran Iraq Ireland Israel Italy Jamaica Japan Jordan Kazakhstan Kenya Kiribati Democratic People's Republic of Korea Republic of Korea Kuwait Kyrgyzstan Lao People's Democratic Republic Latvia Lebanon Lesotho Liberia Libyan Arab Jamahiriya Liechtenstein Lithuania Luxembourg Macao The Former Yugoslav Republic of Macedonia Madagascar Malawi Malaysia Maldives Mali Malta Marshall Islands Martinique Mauritania Mauritius Mayotte Mexico Federated States of Micronesia Republic of Moldova Monaco Mongolia Montserrat Morocco Mozambique
Page 18
DivXMux Command Line Reference
MM NA NR NP NL AN NC NZ NI NE NG NU NF MP NO OM PK PW PS PA PG PY PE PH PN PL PT PR QA RE RO RU RW SH KN LC PM VC WS SM ST SA SN CS SC SL SG SK
DivX, Inc.
Myanmar Namibia Nauru Nepal Netherlands Netherlands Antilles New Caledonia New Zealand Nicaragua Niger Nigeria Niue Norfolk Island Northern Mariana Islands Norway Oman Pakistan Palau Occupied Palestinian Territory Panama Papua New Guinea Paraguay Peru Philippines Pitcairn Poland Portugal Puerto Rico Qatar Reunion Romania Russian Federation Rwanda Saint Helena Saint Kitts and Nevis Saint Lucia Saint Pierre and Miquelon Saint Vincent and the Grenadines Samoa San Marino Sao Tome And Principe Saudi Arabia Senegal Serbia And Montenegro Seychelles Sierra Leone Singapore Slovakia
Page 19
DivXMux Command Line Reference
SI SB SO ZA GS ES LK SD SR SJ SZ SE CH SY TW TJ TZ TH TL TG TK TO TT TN TR TM TC TV UG UA AE GB US UM UY UZ VU VE VN VG VI WF EH YE ZM ZW
DivX, Inc.
Slovenia Solomon Islands Somalia South Africa South Georgia and the South Sandwich Islands Spain Sri Lanka Sudan Suriname Svalbard and Jan Mayen Swaziland Sweden Switzerland Syrian Arab Republic Taiwan, Province of China Tajikistan United Republic of Tanzania Thailand Timor-Leste Togo Tokelau Tonga Trinidad and Tobago Tunisia Turkey Turkmenistan Turks and Caicos Islands Tuvalu Uganda Ukraine United Arab Emirates United Kingdom United States United States Minor Outlying Islands Uruguay Uzbekistan Vanuatu Venezuela Viet Nam Virgin Islands, British Virgin Islands, U.S. Wallis And Futuna Western Sahara Yemen Zambia Zimbabwe
Page 20
DivXMux Command Line Reference
DivX, Inc.
Page 21
