Difference between revisions of "Osd subtitle.xml"

From MythTV Official Wiki
Jump to: navigation, search
m (Copied in the latest version of the reference implementation, which has improved formatting and documentation.)
m (Can now control background transparency of teletext captions.)
 
(3 intermediate revisions by the same user not shown)
Line 21: Line 21:
  
 
{{Note box|'''Teletext formatting'''<br />
 
{{Note box|'''Teletext formatting'''<br />
Currently the only attribute used for teletext subtitles is the font face.
+
Currently the only attributes used for teletext subtitles are the font face
 +
and the background alpha (transparency).
 
Full support will be added later.
 
Full support will be added later.
 
}}
 
}}
Line 62: Line 63:
 
| style="background:silver" | 708_2
 
| style="background:silver" | 708_2
 
| style="background:silver" | CEA-708 closed captions, font tag 2 (proportional_serif)
 
| style="background:silver" | CEA-708 closed captions, font tag 2 (proportional_serif)
| style="background:silver" | DejaVu Serif font, provider background
+
| style="background:silver" | Droid Serif font, provider background
 
|-
 
|-
 
| 708_3
 
| 708_3
Line 72: Line 73:
 
| style="background:silver" | 708_4
 
| style="background:silver" | 708_4
 
| style="background:silver" | CEA-708 closed captions, font tag 4 (proportional_sansserif)
 
| style="background:silver" | CEA-708 closed captions, font tag 4 (proportional_sansserif)
| style="background:silver" | Liberation Sans font, provider background
+
| style="background:silver" | Droid Sans font, provider background
 
|-
 
|-
 
| 708_5
 
| 708_5
Line 82: Line 83:
 
| style="background:silver" | 708_6
 
| style="background:silver" | 708_6
 
| style="background:silver" | CEA-708 closed captions, font tag 6 (cursive)
 
| style="background:silver" | CEA-708 closed captions, font tag 6 (cursive)
| style="background:silver" | URW Chancery L font, provider background
+
| style="background:silver" | TeX Gyre Chorus font, provider background
 
|-
 
|-
 
| 708_7
 
| 708_7
 
| 708_7
 
| 708_7
 
| CEA-708 closed captions, font tag 7 (smallcaps)
 
| CEA-708 closed captions, font tag 7 (smallcaps)
| Impact font, provider background
+
| Droid Serif font, SmallCaps capitalization, provider background
 
|}
 
|}
 
</center>
 
</center>
Line 152: Line 153:
 
           <type>box</type>
 
           <type>box</type>
 
           <fill color="#000000" alpha="255" />
 
           <fill color="#000000" alpha="255" />
 +
          <line color="#000000" alpha="255" width="0" />
 
         </shape>
 
         </shape>
  
Line 173: Line 175:
 
         <fontdef name="teletext" face="FreeMono" from="provider">
 
         <fontdef name="teletext" face="FreeMono" from="provider">
 
         </fontdef>
 
         </fontdef>
 +
 +
<!--
 +
    This allows overriding the alpha (transparency) value of
 +
    non-transparent subtitles.  Note that the parser requires
 +
    some color to be specified here, but it will be ignored
 +
    and the provider's value will be used instead.
 +
  -->
 +
        <shape  name="teletext" from="provider">
 +
          <fill color="#000000" alpha="255" />
 +
        </shape>
  
  
Line 200: Line 212:
  
 
         <!-- Font tag 2: "Proportional Serif" -->
 
         <!-- Font tag 2: "Proportional Serif" -->
         <fontdef name="708_2" face="DejaVu Serif"   from="provider">
+
         <fontdef name="708_2" face="Droid Serif"     from="provider">
 
         </fontdef>
 
         </fontdef>
  
         <!-- Font tag 3: "Monospaced Serif" -->
+
         <!-- Font tag 3: "Monospaced Sans Serif" -->
 
         <fontdef name="708_3" face="Droid Sans Mono" from="provider">
 
         <fontdef name="708_3" face="Droid Sans Mono" from="provider">
 
         </fontdef>
 
         </fontdef>
  
 
         <!-- Font tag 4: "Proportional Sans Serif" -->
 
         <!-- Font tag 4: "Proportional Sans Serif" -->
         <fontdef name="708_4" face="Liberation Sans" from="provider">
+
         <fontdef name="708_4" face="Droid Sans"     from="provider">
 
         </fontdef>
 
         </fontdef>
  
Line 216: Line 228:
  
 
         <!-- Font tag 6: "Cursive" -->
 
         <!-- Font tag 6: "Cursive" -->
         <fontdef name="708_6" face="URW Chancery L" from="provider">
+
         <fontdef name="708_6" face="TeX Gyre Chorus" from="provider">
 
         </fontdef>
 
         </fontdef>
  
 
         <!-- Font tag 7: "Small Capitals" -->
 
         <!-- Font tag 7: "Small Capitals" -->
         <fontdef name="708_7" face="Impact"         from="provider">
+
<!-- Note: The Qt property QFont::SmallCaps is automatically
 +
    applied to this font. -->
 +
         <fontdef name="708_7" face="Droid Serif"     from="provider">
 
         </fontdef>
 
         </fontdef>
  

Latest revision as of 15:15, 11 May 2015

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.


Important.png Note: Teletext formatting
Currently the only attributes used for teletext subtitles are the font face and the background alpha (transparency). 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) Droid 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) Droid 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) TeX Gyre Chorus font, provider background
708_7 708_7 CEA-708 closed captions, font tag 7 (smallcaps) Droid Serif font, SmallCaps capitalization, 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" />
          <line color="#000000" alpha="255" width="0" />
        </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>

	<!--
	    This allows overriding the alpha (transparency) value of
	    non-transparent subtitles.  Note that the parser requires
	    some color to be specified here, but it will be ignored
	    and the provider's value will be used instead.
	   -->
        <shape   name="teletext" from="provider">
          <fill color="#000000" alpha="255" />
        </shape>


        <!--
            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="Droid Serif"     from="provider">
        </fontdef>

        <!-- Font tag 3: "Monospaced Sans Serif" -->
        <fontdef name="708_3" face="Droid Sans Mono" from="provider">
        </fontdef>

        <!-- Font tag 4: "Proportional Sans Serif" -->
        <fontdef name="708_4" face="Droid 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="TeX Gyre Chorus" from="provider">
        </fontdef>

        <!-- Font tag 7: "Small Capitals" -->
	<!-- Note: The Qt property QFont::SmallCaps is automatically
	     applied to this font. -->
        <fontdef name="708_7" face="Droid Serif"     from="provider">
        </fontdef>

    </window>
</mythuitheme>