Difference between revisions of "Osd subtitle.xml"
Jstichnoth (talk | contribs) m (Added links for fontdef and shape.) |
Jstichnoth (talk | contribs) m (Copied in the latest version of the reference implementation, which has improved formatting and documentation.) |
||
Line 130: | Line 130: | ||
<!DOCTYPE mythuitheme SYSTEM "http://www.mythtv.org/schema/mythuitheme.dtd"> | <!DOCTYPE mythuitheme SYSTEM "http://www.mythtv.org/schema/mythuitheme.dtd"> | ||
<mythuitheme> | <mythuitheme> | ||
− | + | <window name="osd_subtitle"> | |
− | + | <!-- | |
− | + | This is a reference implementation of the system/provider | |
− | + | defaults specified in | |
+ | SubtitleFormat:CreateProviderDefault(). | ||
− | + | Note that if all attributes/elements are simply inherited | |
− | + | from provider, then the specification is optional. E.g., | |
− | + | the following could be omitted: | |
− | + | <fontdef name="sample" from="provider"></fontdef> | |
− | + | <shape name="sample" from="provider"></shape> | |
− | + | Also note that these specific definitions are unnecessary | |
− | + | since they are the same as the defaults in the code. A | |
− | + | theme only needs to include the definitions that it wants | |
− | + | to change/override. | |
+ | --> | ||
− | + | <shape name="black_background" from="provider"> | |
− | + | <type>box</type> | |
− | + | <fill color="#000000" alpha="255" /> | |
− | + | </shape> | |
− | |||
− | |||
− | |||
− | |||
− | + | <!-- | |
− | + | Subtitle type "text" generally comes from external text | |
+ | files like .srt or .txt files. | ||
+ | --> | ||
+ | <fontdef name="text" face="Droid Sans" from="provider"> | ||
+ | </fontdef> | ||
− | + | <shape name="text" from="black_background"> | |
− | + | </shape> | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | </window> | + | <!-- |
+ | Digital teletext text-based subtitles. Not to be confused | ||
+ | with bitmap teletext subtitles, or CEA-608 teletext | ||
+ | captions. A monospaced font should be used. | ||
+ | --> | ||
+ | <fontdef name="teletext" face="FreeMono" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | |||
+ | <!-- | ||
+ | CEA-608 closed captions. These also apply to CEA-608 VBI | ||
+ | teletext captions. A monospaced font should be used. | ||
+ | --> | ||
+ | <fontdef name="608" face="FreeMono" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | <shape name="608" from="black_background"> | ||
+ | </shape> | ||
+ | |||
+ | |||
+ | <!-- | ||
+ | CEA-708 closed captions. The spec defines 8 different | ||
+ | font tags, but in practice (at least in the U.S.), only | ||
+ | tags 0 and 3 are used by broadcasters. | ||
+ | --> | ||
+ | <!-- Font tag 0: "Default" --> | ||
+ | <fontdef name="708_0" face="FreeMono" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | <!-- Font tag 1: "Monospaced Serif" --> | ||
+ | <fontdef name="708_1" face="FreeMono" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | <!-- Font tag 2: "Proportional Serif" --> | ||
+ | <fontdef name="708_2" face="DejaVu Serif" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | <!-- Font tag 3: "Monospaced Serif" --> | ||
+ | <fontdef name="708_3" face="Droid Sans Mono" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | <!-- Font tag 4: "Proportional Sans Serif" --> | ||
+ | <fontdef name="708_4" face="Liberation Sans" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | <!-- Font tag 5: "Casual" --> | ||
+ | <fontdef name="708_5" face="Purisa" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | <!-- Font tag 6: "Cursive" --> | ||
+ | <fontdef name="708_6" face="URW Chancery L" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | <!-- Font tag 7: "Small Capitals" --> | ||
+ | <fontdef name="708_7" face="Impact" from="provider"> | ||
+ | </fontdef> | ||
+ | |||
+ | </window> | ||
</mythuitheme> | </mythuitheme> | ||
</pre> | </pre> |
Revision as of 22:28, 8 May 2012
The osd_subtitle.xml file governs the formatting of the font and background for text-based subtitles and captions. Two common uses are to change the font and to customize the background, such as using no background or a translucent background. This applies to text, teletext, CEA-608, and CEA-708 captions.
Basics
Definitions must appear within the osd_subtitle window. The only relevant MythUI objects are fontdef (for the text font attributes) and shape (for the background attributes). The name of each fontdef and shape corresponds to the subtitle type. Each fontdef and shape should ultimately inherit from a special object named "provider", which represents the default formatting of a particular subtitle, and the fontdef or shape can override any of the provider attributes with custom values.
All elements and attributes of fontdef and shape are supported, except that the area and size elements are explicitly ignored, as they are determined by the subtitle drawing code.
Note: Teletext formatting
Currently the only attribute used for teletext subtitles is the font face.
Full support will be added later.
Subtitle types
Fontdef Name | Shape Name | Description | Defaults |
text | text | Text file based subtitles, such as .srt files | Droid Sans font, solid black background |
teletext | teletext | Teletext subtitles | FreeMono font, provider background |
608 | 608 | CEA-608 closed captions | FreeMono font, solid black background |
708_0 | 708_0 | CEA-708 closed captions, font tag 0 (default) | FreeMono font, provider background |
708_1 | 708_1 | CEA-708 closed captions, font tag 1 (monospaced_serif) | FreeMono font, provider background |
708_2 | 708_2 | CEA-708 closed captions, font tag 2 (proportional_serif) | DejaVu Serif font, provider background |
708_3 | 708_3 | CEA-708 closed captions, font tag 3 (monospaced_sansserif) | Droid Sans Mono font, provider background |
708_4 | 708_4 | CEA-708 closed captions, font tag 4 (proportional_sansserif) | Liberation Sans font, provider background |
708_5 | 708_5 | CEA-708 closed captions, font tag 5 (casual) | Purisa font, provider background |
708_6 | 708_6 | CEA-708 closed captions, font tag 6 (cursive) | URW Chancery L font, provider background |
708_7 | 708_7 | CEA-708 closed captions, font tag 7 (smallcaps) | Impact font, provider background |
Example
The following example forces .srt subtitles to be rendered in yellow text, FreeSans font, black shadow, with a translucent black background. The fontdef and shape names are "text" since the subtitles come from a .srt file. Note that in this example, color formatting controls in the .srt file will be ignored due to the explicit setting of yellow text.
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE mythuitheme SYSTEM "http://www.mythtv.org/schema/mythuitheme.dtd"> <mythuitheme> <window name="osd_subtitle"> <fontdef name="text" face="FreeSans" from="provider"> <color>#FFFF00</color> <shadowoffset>2,2</shadowoffset> <shadowcolor>#000000</shadowcolor> </fontdef> <shape name="text" from="provider"> <fill color="#000000" alpha="100" /> </shape> </window> </mythuitheme>
Reference implementation
The themes/default/osd_subtitle.xml file contains a "reference implementation" that explicitly describes the implicit defaults for the various subtitle types in the case that the theme does not provide any specification. As such, these definitions are redundant, but they are provided as documentation and as a template for the theme writer to extend.
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE mythuitheme SYSTEM "http://www.mythtv.org/schema/mythuitheme.dtd"> <mythuitheme> <window name="osd_subtitle"> <!-- This is a reference implementation of the system/provider defaults specified in SubtitleFormat:CreateProviderDefault(). Note that if all attributes/elements are simply inherited from provider, then the specification is optional. E.g., the following could be omitted: <fontdef name="sample" from="provider"></fontdef> <shape name="sample" from="provider"></shape> Also note that these specific definitions are unnecessary since they are the same as the defaults in the code. A theme only needs to include the definitions that it wants to change/override. --> <shape name="black_background" from="provider"> <type>box</type> <fill color="#000000" alpha="255" /> </shape> <!-- Subtitle type "text" generally comes from external text files like .srt or .txt files. --> <fontdef name="text" face="Droid Sans" from="provider"> </fontdef> <shape name="text" from="black_background"> </shape> <!-- Digital teletext text-based subtitles. Not to be confused with bitmap teletext subtitles, or CEA-608 teletext captions. A monospaced font should be used. --> <fontdef name="teletext" face="FreeMono" from="provider"> </fontdef> <!-- CEA-608 closed captions. These also apply to CEA-608 VBI teletext captions. A monospaced font should be used. --> <fontdef name="608" face="FreeMono" from="provider"> </fontdef> <shape name="608" from="black_background"> </shape> <!-- CEA-708 closed captions. The spec defines 8 different font tags, but in practice (at least in the U.S.), only tags 0 and 3 are used by broadcasters. --> <!-- Font tag 0: "Default" --> <fontdef name="708_0" face="FreeMono" from="provider"> </fontdef> <!-- Font tag 1: "Monospaced Serif" --> <fontdef name="708_1" face="FreeMono" from="provider"> </fontdef> <!-- Font tag 2: "Proportional Serif" --> <fontdef name="708_2" face="DejaVu Serif" from="provider"> </fontdef> <!-- Font tag 3: "Monospaced Serif" --> <fontdef name="708_3" face="Droid Sans Mono" from="provider"> </fontdef> <!-- Font tag 4: "Proportional Sans Serif" --> <fontdef name="708_4" face="Liberation Sans" from="provider"> </fontdef> <!-- Font tag 5: "Casual" --> <fontdef name="708_5" face="Purisa" from="provider"> </fontdef> <!-- Font tag 6: "Cursive" --> <fontdef name="708_6" face="URW Chancery L" from="provider"> </fontdef> <!-- Font tag 7: "Small Capitals" --> <fontdef name="708_7" face="Impact" from="provider"> </fontdef> </window> </mythuitheme>