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