1schema_version: 0.3
2type: producer
3identifier: pango
4title: Pango
5version: 2
6copyright: Meltytech, LLC
7creator: Dan Dennedy
8license: LGPLv2.1
9language: en
10tags:
11  - Video
12description: >
13  A title generator that uses the Pango international text layout and Freetype2
14  font renderer.
15notes: >
16  Supplying a filename with extension ".txt" causes the loader producer to load
17  with pango. If the filename begins with "+" the pango producer interprets the
18  filename as pango text. This is a shortcut to embed titles in melt commands.
19  For MLT XML, it is recommended that you embed the title text in the property
20  value.
21
22  Pango has builtin scaling. It will rescale the originally rendered title to
23  whatever the consumer requests. Therefore, it will lose its aspect ratio if
24  so requested, and it is up to the consumer to request a proper width and
25  height that maintains the image aspect.
26
27  Environment variable MLT_PANGO_PRODUCER_CACHE could be used to override and
28  increase the size of cached converted images of simultaneous use.
29
30  Fontset used by pango producer loaded once. That behavior prevents using new
31  fonts till process used pango producer been restarted. To force fontmap reload
32  you need to send signal "fontmap-reload" to pango producer:
33    {
34        mlt_profile profile = mlt_profile_init("dv_pal");
35        mlt_producer producer = mlt_factory_producer(profile, "pango", NULL);
36        mlt_events_fire(mlt_producer_properties(producer), "fontmap-reload", NULL, NULL );
37        mlt_producer_close(producer);
38        mlt_profile_close(profile);
39    };
40
41
42parameters:
43  - identifier: resource
44    title: File
45    type: string
46    description: |
47      A text file containing Pango markup, see:
48      https://developer.gnome.org/pango/stable/PangoMarkupFormat.html
49      requires xml-like encoding special chars from:
50      <, >, &   -to-   &lt;, &gt;, &amp;
51    readonly: no
52    argument: yes
53    mutable: no
54    widget: fileopen
55
56  - identifier: markup
57    title: Markup
58    type: string
59    description: |
60      A string containing Pango markup see:
61      http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
62      requires xml-like encoding special chars from:
63      <, >, &   -to-   &lt;, &gt;, &amp;
64    readonly: no
65    argument: yes
66    mutable: yes
67    widget: textbox
68
69  - identifier: fgcolour
70    title: Foreground color
71    type: string
72    description: >
73      A color value is a hexadecimal representation of RGB plus alpha channel
74      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
75      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
76    readonly: no
77    mutable: yes
78    widget: color
79
80  - identifier: bgcolour
81    title: Background color
82    type: string
83    description: >
84      A color value is a hexadecimal representation of RGB plus alpha channel
85      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
86      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
87    readonly: no
88    mutable: yes
89    widget: color
90
91  - identifier: olcolour
92    title: Outline color
93    type: string
94    description: >
95      A color value is a hexadecimal representation of RGB plus alpha channel
96      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
97      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
98    readonly: no
99    mutable: yes
100    widget: color
101
102  - identifier: outline
103    title: Outline Width
104    type: string
105    description: >
106      The width of the outline in pixels.
107    readonly: no
108    default: 0
109    minimum: 0
110    maximum: 3
111    mutable: yes
112    widget: spinner
113    unit: pixels
114
115  - identifier: align
116    title: Paragraph alignment
117    type: string
118    description: >
119      left, centre, right (also, numbers 0, 1 and 2 can be used respectively)
120    readonly: no
121    default: left
122    mutable: yes
123    widget: combo
124
125  - identifier: pad
126    title: Padding
127    type: integer
128    description: >
129      The number of pixels to pad the background rectangle beyond edges of text.
130    readonly: no
131    default: 0
132    mutable: yes
133    widget: spinner
134    unit: pixels
135
136  - identifier: text
137    title: Text
138    type: string
139    description: |
140      A non-markup string in UTF-8 encoding
141      (can contain markup chars un-encoded)
142    readonly: no
143    mutable: yes
144    widget: textbox
145
146  - identifier: font
147    title: Font
148    type: string
149    description: >
150      The default typeface to use when not using markup.
151      FreeType2 renders at 72 dpi.
152      This property is deprecated. Use family, size and style instead.
153    readonly: no
154    mutable: yes
155    widget: combo
156
157  - identifier: family
158    title: Font family
159    type: string
160    description: >
161      The default typeface to use when not using markup.
162    default: Sans
163    readonly: no
164    mutable: yes
165    widget: combo
166
167  - identifier: size
168    title: Font size
169    type: integer
170    description: >
171      The size in pixels of the font to use when not using markup.
172    default: 48
173    readonly: no
174    mutable: yes
175    widget: spinner
176    unit: pixels
177
178  - identifier: style
179    title: Font style
180    type: string
181    description: >
182      The style of the font to use when not using markup.
183    values:
184      - normal
185      - italic
186      - oblique
187    default: normal
188    readonly: no
189    mutable: yes
190    widget: combo
191
192  - identifier: weight
193    title: Font weight
194    type: integer
195    description: The weight of the font.
196    minimum: 100
197    maximum: 1000
198    default: 400
199    readonly: no
200    mutable: yes
201    widget: spinner
202
203  - identifier: encoding
204    title: Encoding
205    type: string
206    description: >
207      The text encoding type of the input if not UTF-8.
208      See 'iconv --list' for a list of possible inputs.
209    default: UTF-8
210    readonly: no
211    mutable: yes
212    widget: combo
213
214  - identifier: real_width
215    title: Real width
216    type: integer
217    description: The original, unscaled width of the rendered title.
218    readonly: yes
219    unit: pixels
220
221  - identifier: real_height
222    title: Real height
223    type: integer
224    description: The original, unscaled height of the rendered title.
225    readonly: yes
226    unit: pixels
227
228  - identifier: width
229    title: Width
230    type: integer
231    description: The last requested scaled image width.
232    readonly: yes
233    unit: pixels
234
235  - identifier: height
236    title: Height
237    type: integer
238    description: The last requested scaled image height.
239    readonly: yes
240    unit: pixels
241
242  - identifier: force_aspect_ratio
243    title: Sample aspect ratio
244    type: float
245    description: Optionally override a (mis)detected aspect ratio
246    mutable: yes
247
248  - identifier: rotate
249    title: Rotation angle
250    type: integer
251    description: >
252      The angle of text rotation in degrees. Positive value is clockwise.
253    default: 0
254    readonly: no
255    mutable: yes
256    widget: spinner
257    unit: degrees
258
259  - identifier: width_crop
260    title: Width to crop
261    type: integer
262    description: >
263      Limit width of rendered image.
264    default: 0
265    readonly: no
266    mutable: yes
267    widget: spinner
268    unit: pixels
269
270  - identifier: width_fit
271    title: Fit width
272    type: integer
273    description: >
274      Scale pango layout to fit specified width.
275    default: 0
276    readonly: no
277    mutable: yes
278    widget: spinner
279    unit: pixels
280
281  - identifier: line_spacing
282    title: Sets lines spacing
283    type: integer
284    description: >
285      Sets the amount of spacing between the lines of the layout.
286    default: 0
287    readonly: no
288    mutable: yes
289    widget: spinner
290
291  - identifier: stretch
292    title: Font stretch
293    type: integer
294    description: >
295      The stretch feature of pango's font description. Possible values:
296        1 - ULTRA_CONDENSED
297        2 - EXTRA_CONDENSED
298        3 - CONDENSED
299        4 - SEMI_CONDENSED
300        5 - NORMAL
301        6 - SEMI_EXPANDED
302        7 - EXPANDED
303        8 - EXTRA_EXPANDED
304        9 - ULTRA_EXPANDED
305    minimum: 0
306    maximum: 9
307    default: 4
308    readonly: no
309    mutable: yes
310    widget: spinner
311
312  - identifier: wrap_width
313    title: Sets the width to wrap to
314    type: integer
315    description: >
316      Sets the width to which the lines of the PangoLayout should wrap.
317    default: 0
318    readonly: no
319    mutable: yes
320    widget: spinner
321    unit: pixels
322
323  - identifier: wrap_type
324    title: Sets the wrap mode
325    type: integer
326    description: >
327      Sets the wrap mode; the wrap mode only has effect if a 'wrap_width' is set.
328      Possible values:
329          0 - wrap lines at word boundaries
330          1 - wrap lines at character boundaries
331          2 - wrap lines at word boundaries, but fall back to character
332              boundaries if there is not enough space for a full word
333    default: 0
334    readonly: no
335    mutable: yes
336    widget: spinner
337