## textoverlay textoverlay — Adds text strings on top of a video buffer |

## Synopsis

    struct              GstTextOverlay;
    enum                GstTextOverlayVAlign;
    enum                GstTextOverlayHAlign;
    enum                GstTextOverlayWrapMode;

## Object Hierarchy

      GObject
       +----GstObject
             +----GstElement
                   +----GstTextOverlay
                         +----GstTimeOverlay
                         +----GstClockOverlay

## Properties

      "deltax"                   gint                  : Read / Write
      "deltay"                   gint                  : Read / Write
      "font-desc"                gchar*                : Write
      "halign"                   gchar*                : Write
      "shaded-background"        gboolean              : Read / Write
      "text"                     gchar*                : Read / Write
      "valign"                   gchar*                : Write
      "wrap-mode"                GstTextOverlayWrapMode  : Read / Write
      "xpad"                     gint                  : Read / Write
      "ypad"                     gint                  : Read / Write
      "halignment"               GstTextOverlayHAlign  : Read / Write
      "valignment"               GstTextOverlayVAlign  : Read / Write
      "line-alignment"           GstTextOverlayLineAlign  : Read / Write
      "silent"                   gboolean              : Read / Write
      "wait-text"                gboolean              : Read / Write
      "auto-resize"              gboolean              : Read / Write
      "vertical-render"          gboolean              : Read / Write
      "color"                    guint                 : Read / Write
      "xpos"                     gdouble               : Read / Write
      "ypos"                     gdouble               : Read / Write

## Description

This plugin renders text on top of a video stream. This can be either static text or text from buffers received on the text sink pad, e.g. as produced by the subparse element. If the text sink pad is not linked, the text set via the "text" property will be rendered. If the text sink pad is linked, text will be rendered as it is received on that pad, honouring and matching the buffer timestamps of both input streams.

The text can contain newline characters and text wrapping is enabled by default.

### Example launch lines

    1
    gst-launch -v videotestsrc ! textoverlay text="Room A" valign=top halign=left ! xvimagesink

Here is a simple pipeline that displays a static text in the top left corner of the video picture

    1
    gst-launch -v filesrc location=subtitles.srt ! subparse ! txt.   videotestsrc ! timeoverlay ! textoverlay name=txt shaded-background=yes ! xvimagesink

Here is another pipeline that displays subtitles from an .srt subtitle file, centered at the bottom of the picture and with a rectangular shading around the text in the background:

If you do not have such a subtitle file, create one looking like this in a text editor:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    1
    00:00:03,000 --> 00:00:05,000
    Hello? (3-5s)

    2
    00:00:08,000 --> 00:00:13,000
    Yes, this is a subtitle. Don't
    you like it? (8-13s)

    3
    00:00:18,826 --> 00:01:02,886
    Uh? What are you talking about?
    I don't understand  (18-62s)

## Synopsis

### Element Information

plugin | pango
author | David Schleef <ds@schleef.org>, Zeeshan Ali <zeeshan.ali@nokia.com>
class | Filter/Editor/Video

### Element Pads

name | text_sink
direction | sink
presence | always
details | text/x-pango-markup
| text/plain

name | video_sink
direction | sink
presence | always
details | video/x-raw-rgb, bpp=(int)32, depth=(int)24, endianness=(int)4321, red_mask=(int)65280, green_mask=(int)16711680, blue_mask=(int)-16777216, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)24, endianness=(int)4321, red_mask=(int)-16777216, green_mask=(int)16711680, blue_mask=(int)65280, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)24, endianness=(int)4321, red_mask=(int)16711680, green_mask=(int)65280, blue_mask=(int)255, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)24, endianness=(int)4321, red_mask=(int)255, green_mask=(int)65280, blue_mask=(int)16711680, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)-16777216, green_mask=(int)16711680, blue_mask=(int)65280, alpha_mask=(int)255, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)65280, green_mask=(int)16711680, blue_mask=(int)-16777216, alpha_mask=(int)255, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)16711680, green_mask=(int)65280, blue_mask=(int)255, alpha_mask=(int)-16777216, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)255, green_mask=(int)65280, blue_mask=(int)16711680, alpha_mask=(int)-16777216, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-yuv, format=(fourcc){ AYUV, I420, UYVY, NV12, NV21 }, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]

name | src
direction | source
presence | always
details | video/x-raw-rgb, bpp=(int)32, depth=(int)24, endianness=(int)4321, red_mask=(int)65280, green_mask=(int)16711680, blue_mask=(int)-16777216, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)24, endianness=(int)4321, red_mask=(int)-16777216, green_mask=(int)16711680, blue_mask=(int)65280, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)24, endianness=(int)4321, red_mask=(int)16711680, green_mask=(int)65280, blue_mask=(int)255, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)24, endianness=(int)4321, red_mask=(int)255, green_mask=(int)65280, blue_mask=(int)16711680, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)-16777216, green_mask=(int)16711680, blue_mask=(int)65280, alpha_mask=(int)255, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)65280, green_mask=(int)16711680, blue_mask=(int)-16777216, alpha_mask=(int)255, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)16711680, green_mask=(int)65280, blue_mask=(int)255, alpha_mask=(int)-16777216, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-rgb, bpp=(int)32, depth=(int)32, endianness=(int)4321, red_mask=(int)255, green_mask=(int)65280, blue_mask=(int)16711680, alpha_mask=(int)-16777216, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw-yuv, format=(fourcc){ AYUV, I420, UYVY, NV12, NV21 }, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]

## Details

### struct GstTextOverlay

    struct GstTextOverlay;

Opaque textoverlay object structure

### enum GstTextOverlayVAlign

    typedef enum {
        GST_TEXT_OVERLAY_VALIGN_BASELINE,
        GST_TEXT_OVERLAY_VALIGN_BOTTOM,
        GST_TEXT_OVERLAY_VALIGN_TOP,
        GST_TEXT_OVERLAY_VALIGN_POS,
        GST_TEXT_OVERLAY_VALIGN_CENTER
    } GstTextOverlayVAlign;

Vertical alignment of the text.

`GST_TEXT_OVERLAY_VALIGN_BASELINE` | draw text on the baseline
`GST_TEXT_OVERLAY_VALIGN_BOTTOM` | draw text on the bottom
`GST_TEXT_OVERLAY_VALIGN_TOP` | draw text on top
`GST_TEXT_OVERLAY_VALIGN_POS` | draw text according to the "ypos" property
`GST_TEXT_OVERLAY_VALIGN_CENTER` | draw text vertically centered

### enum GstTextOverlayHAlign

    typedef enum {
        GST_TEXT_OVERLAY_HALIGN_LEFT,
        GST_TEXT_OVERLAY_HALIGN_CENTER,
        GST_TEXT_OVERLAY_HALIGN_RIGHT,
        GST_TEXT_OVERLAY_HALIGN_UNUSED,
        GST_TEXT_OVERLAY_HALIGN_POS
    } GstTextOverlayHAlign;

Horizontal alignment of the text.

`GST_TEXT_OVERLAY_HALIGN_LEFT` | align text left
`GST_TEXT_OVERLAY_HALIGN_CENTER` | align text center
`GST_TEXT_OVERLAY_HALIGN_RIGHT` | align text right
`GST_TEXT_OVERLAY_HALIGN_UNUSED` |
`GST_TEXT_OVERLAY_HALIGN_POS` | position text according to the "xpos" property

### enum GstTextOverlayWrapMode

    typedef enum {
        GST_TEXT_OVERLAY_WRAP_MODE_NONE = -1,
        GST_TEXT_OVERLAY_WRAP_MODE_WORD = PANGO_WRAP_WORD,
        GST_TEXT_OVERLAY_WRAP_MODE_CHAR = PANGO_WRAP_CHAR,
        GST_TEXT_OVERLAY_WRAP_MODE_WORD_CHAR = PANGO_WRAP_WORD_CHAR
    } GstTextOverlayWrapMode;

Whether to wrap the text and if so how.

`GST_TEXT_OVERLAY_WRAP_MODE_NONE` | no wrapping
`GST_TEXT_OVERLAY_WRAP_MODE_WORD` | do word wrapping
`GST_TEXT_OVERLAY_WRAP_MODE_CHAR` | do char wrapping
`GST_TEXT_OVERLAY_WRAP_MODE_WORD_CHAR` | do word and char wrapping

## Property Details

### The `"deltax"` property

      "deltax"                   gint                  : Read / Write

Shift X position to the left or to the right. Unit is pixels.

Default value: 0

### The `"deltay"` property

      "deltay"                   gint                  : Read / Write

Shift Y position up or down. Unit is pixels.

Default value: 0

### The `"font-desc"` property

      "font-desc"                gchar*                : Write

Pango font description of font to be used for rendering. See documentation of pango_font_description_from_string for syntax.

Default value: ""

### The `"halign"` property

      "halign"                   gchar*                : Write

Horizontal alignment of the text (deprecated; use halignment).

Default value: "center"

### The `"shaded-background"` property

      "shaded-background"        gboolean              : Read / Write

Whether to shade the background under the text area.

Default value: FALSE

### The `"text"` property

      "text"                     gchar*                : Read / Write

Text to be display.

Default value: ""

### The `"valign"` property

      "valign"                   gchar*                : Write

Vertical alignment of the text (deprecated; use valignment).

Default value: "baseline"

### The `"wrap-mode"` property

      "wrap-mode"                GstTextOverlayWrapMode  : Read / Write

Whether to wrap the text and if so how.

Default value: wordchar

### The `"xpad"` property

      "xpad"                     gint                  : Read / Write

Horizontal paddding when using left/right alignment.

Allowed values: >= 0

Default value: 25

### The `"ypad"` property

      "ypad"                     gint                  : Read / Write

Vertical padding when using top/bottom alignment.

Allowed values: >= 0

Default value: 25

### The `"halignment"` property

      "halignment"               GstTextOverlayHAlign  : Read / Write

Horizontal alignment of the text.

Default value: center

### The `"valignment"` property

      "valignment"               GstTextOverlayVAlign  : Read / Write

Vertical alignment of the text.

Default value: baseline

### The `"line-alignment"` property

      "line-alignment"           GstTextOverlayLineAlign  : Read / Write

Alignment of text lines relative to each other (for multi-line text)

Default value: center

Since 0.10.15

### The `"silent"` property

      "silent"                   gboolean              : Read / Write

If set, no text is rendered. Useful to switch off text rendering temporarily without removing the textoverlay element from the pipeline.

Default value: FALSE

Since 0.10.15

### The `"wait-text"` property

      "wait-text"                gboolean              : Read / Write

If set, the video will block until a subtitle is received on the text pad. If video and subtitles are sent in sync, like from the same demuxer, this property should be set.

Default value: TRUE

Since 0.10.20

### The `"auto-resize"` property

      "auto-resize"              gboolean              : Read / Write

Automatically adjust font size to screen-size.

Default value: TRUE

### The `"vertical-render"` property

      "vertical-render"          gboolean              : Read / Write

Vertical Render.

Default value: FALSE

### The `"color"` property

      "color"                    guint                 : Read / Write

Color of the rendered text.

Default value: 4294967295

Since 0.10.31

### The `"xpos"` property

      "xpos"                     gdouble               : Read / Write

Horizontal position of the rendered text when using positioned alignment.

Allowed values: [0,1]

Default value: 0.5

Since 0.10.31

### The `"ypos"` property

      "ypos"                     gdouble               : Read / Write

Vertical position of the rendered text when using positioned alignment.

Allowed values: [0,1]

Default value: 0.5

Since 0.10.31

## See Also

GstTextRender, GstClockOverlay, GstTimeOverlay, GstSubParse