1.. _subtext:
2
3Subtext
4=======
5
6Subtext is a subtitle renderer that uses libass and ffmpeg.
7
8.. function::   TextFile(clip clip, string file[, string charset="UTF-8", float scale=1, int debuglevel=0, string fontdir="", float linespacing=0, int[] margins=[0, 0, 0, 0], float sar=0, string style="", bint blend=True, int matrix, string matrix_s, int transfer, string transfer_s, int primaries, string primaries_s])
9   :module: sub
10
11   TextFile renders text subtitles. Supported formats include ASS,
12   JACOsub, MicroDVD, SAMI, SRT, WebVTT, and some other obscure ones.
13
14   TextFile has two modes of operation. With blend=True (the default),
15   it returns *clip* with the subtitles burned in. With blend=False, it
16   returns a list of two clips. The first one is an RGB24 clip
17   containing the rendered subtitles. The second one is a Gray8 clip
18   containing a mask, to be used for blending the rendered subtitles
19   into other clips.
20
21   Parameters:
22      clip
23         Input clip.
24
25      file
26         Subtitle file to be rendered.
27
28      charset
29         Character set of the subtitle, in iconv format.
30
31      scale
32         Font scale.
33
34      debuglevel
35         Debug level. Increase to make libass more chatty.
36         See `ass_utils.h <https://github.com/libass/libass/blob/master/libass/ass_utils.h>`_
37         in libass for the list of meaningful values.
38
39      fontdir
40         Directory with additional fonts.
41
42      linespacing
43         Space between lines, in pixels.
44
45      margins
46         Additional margins, in pixels. Negative values are not
47         allowed. The order is top, bottom, left, right.
48
49      sar
50         Storage aspect ratio.
51
52      style
53         Custom ASS style for subtitle formats other than ASS. If empty
54         (the default), libavcodec's default style is used. This
55         parameter has no effect on ASS subtitles.
56
57      blend
58         If True, the subtitles will be blended into *clip*. Otherwise,
59         the bitmaps will be returned untouched.
60
61      matrix
62
63      matrix_s
64
65      transfer
66
67      transfer_s
68
69      primaries
70
71      primaries_s
72         If blend=True, these will be passed to resize.Bicubic when
73         converting the RGB24 subtitles to YUV. The default matrix is
74         "709".
75
76
77.. function::   Subtitle(clip clip, string text[, int start=0, int end=clip.numFrames, int debuglevel=0, string fontdir="", float linespacing=0, int[] margins=[0, 0, 0, 0], float sar=0, string style="sans-serif,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,0,7,10,10,10,1", bint blend=True, int matrix, string matrix_s, int transfer, string transfer_s, int primaries, string primaries_s])
78   :module: sub
79
80   Instead of rendering a subtitle file, Subtitle renders the string *text*.
81   Otherwise it works the same as TextFile.
82
83   Parameters:
84      text
85         String to be rendered. This can include ASS tags to enable rich text and animation.
86
87      style
88         Custom ASS style to be used.
89
90      start, end
91         Subtitle will be shown from *start* up until *end*. By default this will be for all frames in *clip*.
92
93   The other parameters have the same meanings as with TextFile.
94
95
96.. function::   ImageFile(clip clip, string file[, int id=-1, int[] palette, bint gray=False, bint info=False, bint flatten=False, bint blend=True, int matrix, string matrix_s, int transfer, string transfer_s, int primaries, string primaries_s])
97   :module: sub
98
99   ImageFile renders image-based subtitles such as VOBSUB and PGS.
100
101   ImageFile has two modes of operation. With blend=True (the default),
102   it returns *clip* with the subtitles burned in. With blend=False, it
103   returns an RGB24 clip containing the rendered subtitles, with a Gray8
104   frame attached to each frame in the ``_Alpha`` frame property. These
105   Gray8 frames can be extracted using std.PropToClip.
106
107   Parameters:
108      *clip*
109         If *blend* is True, the subtitles will be burned into this
110         clip, Otherwise, only the frame rate and number of frames
111         will be obtained from this clip.
112
113      *file*
114         Name of the subtitle file. For VOBSUB, it must the name of the
115         idx file. The corresponding sub file must be in the same
116         folder, and it must have the same name.
117
118      *id*
119         Id of the subtitle track to render. There may be several
120         subtitle tracks in the same file. If this is -1, the first
121         supported subtitle track will be rendered. Use info=True to
122         see a list of all subtitle tracks, including their ids.
123
124         Default: -1.
125
126      *palette*
127         Custom palette. This is an array of at most 256 integers. Each
128         element's least significant four bytes must contain the values
129         for alpha, red, green, and blue, in that order, from most
130         significant to least.
131
132         Additionally, the special value 2**42 means that the
133         corresponding element of the original palette is used. This
134         way it is possible to override only the third element, without
135         overriding the first and second ones, for example.
136
137         An alpha value of 255 means the colour will be completely
138         opaque, and a value of 0 means the colour will be completely
139         transparent.
140
141      *gray*
142         If True, the subtitles will be turned gray.
143
144         Default: False.
145
146      *info*
147         If this is True, a list of all supported subtitle tracks found
148         in the file will be printed on each frame of the output. The
149         information printed about each track includes the id, the
150         language (if known), the resolution, and the format.
151
152         Default: False.
153
154      *flatten*
155         If this is True, ImageFile will output a clip with exactly as
156         many frames as there are pictures in the subtitle file.
157
158         If this is True, *blend* has no effect (no automatic blending).
159
160         Default: False.
161
162   The other parameters have the same meanings as with TextFile.
163
164
165Example with manual blending::
166
167   subs = core.sub.TextFile(clip=YUV420P10_video, file="asdf.ass", blend=False)
168
169   gray10 = core.register_format(subs[1].format.color_family,
170                                 YUV420P10_video.format.sample_type,
171                                 YUV420P10_video.format.bits_per_sample,
172                                 subs[1].format.subsampling_w,
173                                 subs[1].format.subsampling_h)
174
175   subs[0] = core.resize.Bicubic(clip=subs[0], format=YUV420P10_video.format.id, matrix_s="470bg")
176   subs[1] = core.resize.Bicubic(clip=subs[1], format=gray10.id)
177
178   hardsubbed_video = core.std.MaskedMerge(clipa=YUV420P10_video, clipb=subs[0], mask=subs[1])
179
180Example with automatic blending (will use BT709 matrix)::
181
182   hardsubbed_video = core.sub.TextFile(clip=YUV420P10_video, file="asdf.ass")
183
184Example with a custom palette and automatic blending::
185
186   def rgba(r, g, b, a=255):
187       if r < 0 or r > 255 or g < 0 or g > 255 or b < 0 or b > 255 or a < 0 or a > 255:
188           raise vs.Error("Colours must be in the range [0, 255].")
189
190       return (a << 24) + (r << 16) + (g << 8) + b
191
192   unused = 1 << 42
193
194   src = core.ffms2.Source("video.mp4")
195
196   # Override only the third element of the palette. Set it to some kind of green.
197   ret = core.sub.ImageFile(src, "subtitles.sup", palette=[unused, unused, rgba(0, 192, 128)])
198