Subtitle

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

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.

This filter is used internally by AviSynth for Version, ShowFrameNumber and for reporting error messages.

Parameters

text

The text to be displayed.

x, y

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: 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. Starting from v2.60 they can be float.

first_frame, last_frame

The text will be shown starting from frame first_frame and ending with frame last_frame.

Default values: first_frame=0, last_frame=Framecount(clip)-1

font

Font name; default "Arial".

All installed fonts on the current machine are available; they are located in your 'windows\fonts' folder.

size

Height of the text in pixels, and is rounded to the nearest 0.125 pixel. Default 18.

text_color, halo_color

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.

align

Set where the text is placed, based on the numeric keypad layout, as follows:

	Left	Center	Right
Top	7	8	9	top of text at y.
Middle	4	5	6	baseline of text at y.
Bottom	1	2	3	bottom of text at y.
	start at x.	center on x.	end at x.

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.

spc

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.

For more information, see the Microsoft documentation of the function SetTextCharacterExtra().

lsp

Line Spacing Parameter; enables multi-line text (where "\n" enters a line break) and sets the additional inter-line spacing (if any) in 0.125 pixel units. Multi-line text was added in v2.57. Default undefined, which disables multi-line text.

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".

font_width

Set character width in logical units, to the nearest 0.125 unit. Default=0, use Windows' default width.

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().

font_angle

Adjust the baseline angle of text in degrees anti-clockwise to the nearest 0.1 degree. Default 0, no rotation.

interlaced

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

# Some text in the center of the clip:
AviSource("D:\clip.avi")
Subtitle("Hello world!", align=5)

# Some text in the upper right corner of the clip with specified font, size and color:
AviSource("D:\clip.avi")
Subtitle("Hello world!", font="georgia", size=24, text_color=$ff0000, align=9)

# Prints text on multiple lines
# without any text 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()))

Demonstrate extreme values of spc, font_width and lsp:

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 = -64.0
maxvalue = +128.0
return Animate(Last, 0, 255, "anim_spc", s1, minvalue , s1, maxvalue)
   \ + BlankClip(Last, length=10)
   \ + Animate(Last, 0, 255, "anim_wid", s1, minvalue , s1, maxvalue)
   \ + BlankClip(Last, length=10)
   \ + Animate(Last, 0, 255, "anim_lsp", s3, minvalue , s3, maxvalue)
function anim_spc(clip C, string s, float f){
    return C.Subtitle(s, align=8, size=16, font="Arial", spc=0)
    \       .Subtitle(s, align=5, size=16, font="Arial", spc=Round(f))
    \       .Subtitle("spc = "+String(Round(f)), align=2, size=32)
}
function anim_wid(clip C, string s, float f){
    return C.Subtitle(s, align=8, size=16, font="Arial", font_width=0)
    \       .Subtitle(s, align=5, size=16, font="Arial", font_width=f)
    \       .Subtitle("font_width = "+String(Round(f)), align=2, size=32)
}
function anim_lsp(clip C, string s, float f){
    return C.Subtitle(s, align=8, size=16, font="Arial", lsp=0)
    \       .Subtitle(s, align=5, size=16, font="Arial", lsp=Round(f))
    \       .Subtitle("lsp = "+String(Round(f)), align=2, size=32)
}

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.