Subtitle

From Avisynth wiki
Jump to: navigation, search

The Subtitle filter adds anti-aliased text to a range of frames. All parameters after text are optional and can be omitted or specified out of order using the name=value syntax.

The short form (with all default parameters) is useful when you don't really care what the subtitle looks like as long as you can see it—for example, when you're using StackVertical and its ilk to display several versions of a frame at once, and you want to label them to remember which is which.

Contents

Syntax and Parameters

Subtitle(clip clip, string text, float x, float y, int first_frame, int last_frame,
      string font, float size, int text_color, int halo_color, int align, int spc, int lsp,
      float font_width, float font_angle, bool interlaced)

string  text =
The text to be displayed.
float  x = (auto)
float  y = (auto)
Text position. Can be set to -1 to automatically center the text horizontally or vertically, respectively. Negative values of x and y not equal to -1 can be used to move subtitles partially off the screen.
Default values:
x = 8 if align=1,4,7 or none; -1 if align=2,5,8; or width-8 if align=3,6,9
y = size if align=4,5,6 or none; 0 if align=7,8,9; or height-1 if align=1,2,3
Caution: Using v2.58 or older, if your script uses Subtitle with Animate and negative x or y values, x or y might momentarily become -1, causing a glitch in the video.
int  first_frame = 0
int  last_frame = (clip.Framecount-1)
The text will be shown starting from frame first_frame and ending with frame last_frame.
string  font = "Arial"
Font name; can be the name of any installed Windows font.
float  size = 18.0
Height of the text in pixels, and is rounded to the nearest 0.125 pixel. Default 18.
int  text_color = color_yellow
int  halo_color = color_black
Colors for font fill and outline respectively. Default yellow, black.

These may be any of the Preset colors, or specified as hexadecimal $aarrggbb values, similar to HTML--except that they start with $ instead of # and the 4th octet specifies the alpha transparency. $00rrggbb is completely opaque, $FF000000 is fully transparent. You can disable the halo by selecting this color. See Colors for more information on specifying colors.

int  align = 7
Set where the text is placed, based on the numeric keypad layout, as follows:

Subtitle-align-chart.png

Subtitle-align-demo.png

Default 7, or top-left. If x and/or y are given, text is positioned relative to the (x,y) location. Note there is no Y-center alignment setting.
int  spc = 0
Modify the inter-character spacing. If spc is less than zero, inter-character spacing is decreased; if greater, the spacing is increased. Default is 0: use Windows' default spacing.
This is helpful for trying to match typical fonts on the PC to fonts used in film and television credits which are usually wider for the same height or to just fit or fill in a space with a fixed per-character adjustment. See example below.
For more information, see the Microsoft documentation of the function SetTextCharacterExtra().
int  lsp =
Line Spacing Parameter; enables multi-line text (where "\n" enters a line break). If lsp is less than zero, inter-line spacing is decreased; if greater, the spacing is increased, relative to Windows' default spacing. By default, multi-line text disabled.
In the unlikely event that you want to output the characters "\n" literally in a multi-line text, you can do this by using "\\n".
float  font_width = 0.0
Set character width in logical units, to the nearest 0.125 unit. Default=0, use Windows' default width. See example below.
Character width varies, depending on the font face and size, but "Arial" at size=16 is about 7 units wide; if font_width is less than that, (but greater than zero), the text is squeezed, and if it is greater, the text is stretched. Negative numbers are converted to their absolute values.
For more information, see the Microsoft documentation of the function CreateFont().
float  font_angle = 0.0
Adjust the baseline angle of text in degrees anti-clockwise to the nearest 0.1 degree. Default 0, no rotation.
bool  interlaced = false
When enabled, reduces flicker from sharp fine vertical transitions on interlaced displays. It applies a mild vertical blur by increasing the anti-aliasing window to include 0.5 of the pixel weight from the lines above and below. Default=false.

Examples

Center text
AviSource("D:\clip.avi")
Subtitle("Hello world!", align=5)
Text in upper right corner with specified font, size and color
AviSource("D:\clip.avi")
Subtitle("Hello world!", font="georgia", size=24, text_color=$ff0000, align=9)
Print text on multiple lines with no halo border
BlankClip()
Subtitle( \
  "Some text on line 1\\nMore text on line 1\n" + \
  "Some text on line 2", \
         lsp=10, halo_color=$ff000000)

It results in:

Some text on line 1\nMore text on line 1
Some text on line 2
Use String() to display values of functions
AviSource("D:\clip.avi")
Subtitle("Width=" + String(Width()))
Using spc and font_width arguments
ColorBars.KillAudio
Subtitle("ROYGBIV", x=-1, y=100, spc=-10, font_width=6)
Subtitle("ROYGBIV", x=-1, y=150, spc=0,  font_width=0) ## width=default 
Subtitle("ROYGBIV", x=-1, y=200, spc=10, font_width=10)
Subtitle("ROYGBIV", x=-1, y=250, spc=20, font_width=20)

Subtitle width.jpg

Animated parameter demonstration
ColorbarsHD(width=640, height=360)
AmplifyDB(-30)
Tweak(cont=0.5, sat=0.5)
ConvertToRGB32(matrix="PC.709")
Trim(0, 255)
s1 = "THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG."
s3 = "THE QUICK BROWN FOX \nJUMPS OVER \nTHE LAZY DOG."
minvalue = -32.0
maxvalue = +128.0
B = BlankClip(Last, length=15)
return Animate(Last, 0, 255, "anim_aln", s3, 1.000000, s3, 9.999999)
   \ + B
   \ + Animate(Last, 0, 255, "anim_spc", s1, minvalue, s1, maxvalue)
   \ + B
   \ + Animate(Last, 0, 255, "anim_wid", s1, minvalue, s1, maxvalue)
   \ + B
   \ + Animate(Last, 0, 255, "anim_lsp", s3, minvalue, s3, maxvalue)
   \ + B
   \ + Animate(Last, 0, 255, "anim_ang", s1, -15.0000, s1, 375.0000).FadeOut(15)
function anim_aln(clip C, string s, float f) {
    return C.Subtitle(s, align=Floor(f), lsp=0)
    \       .Subtitle("align = "+String(Floor(f)), 
    \                 x=-1, y=C.Height-42, size=32, text_color=$c0c0c0)
}
function anim_spc(clip C, string s, float f) {
    return C.Subtitle(s, align=8, spc=0, text_color=$c0c0c0)
    \       .Subtitle(s, align=5, spc=Round(f))
    \       .Subtitle("spc = "+String(Round(f)), 
    \                 align=2, size=32, text_color=$c0c0c0)
}
function anim_wid(clip C, string s, float f) {
    return C.Subtitle(s, align=8, font_width=0, text_color=$c0c0c0)
    \       .Subtitle(s, align=5, font_width=Round(f))
    \       .Subtitle("font_width = "+String(Round(f)), 
    \                 align=2, size=32, text_color=$c0c0c0)
} 
function anim_lsp(clip C, string s, float f) {
    return C.Subtitle(s, align=8, lsp=0, text_color=$c0c0c0)
    \       .Subtitle(s, align=5, lsp=Round(f))
    \       .Subtitle("lsp = "+String(Round(f)), 
    \                 align=2, size=32, text_color=$c0c0c0)
}
function anim_ang(clip C, string s, float f) {
    return C.Subtitle(s, align=5, font_angle=f)
    \       .Subtitle("font_angle = "+String(f, "%03.3f"), 
    \                 align=2, size=32, text_color=$c0c0c0)
}


Changes

v2.60 position (x,y) can be float (previously int) (with 0.125 pixel granularity).
v2.58 Added font_width, font_angle, interlaced and alpha color blending.
v2.57 Added multi-line text and line spacing parameter.
v2.56 changed default align parameter: from "default = 4, if x == -1 then 5" to "default = 7, if x == -1 then 2"
v2.07 Added align and spc parameters. Setting y=-1 calculates vertical center (alignment unaffected). Default x and y values dependent on alignment (previously x=8, y=size).
v1.00 Setting x=-1 uses horizontal center and center alignment (undocumented prior to v2.07).


See also

There are external subtitling filters that display SRT, SSA, and other format subtitle files or offer more elaborate formatting.

Personal tools