View source for Documentation:Modules/marq

{{Module|name=marq|type=Video sub-filter|first_version=0.8.0|description=Overlays text on the video|sc=marq}}

The marq sub-filter can be used to display text on a video. The {{docmod|time}} filter was merged with this filter in version 0.9.0.

== Options ==
<onlyinclude>{{Option
|name=marq-marquee
|value=string
|default=VLC
|description=Marquee text to display. Since VLC version 0.9.0 you can use [[Documentation:Format String|format strings]] to display time information
}}
{{Option
|name=marq-file
|value=string
|description=File to read the marquee text from
}}
{{Option
|name=marq-x
|value=integer
|default=0 (0.8.6d and prior: -1)
|description=X offset from upper left corner. (0.8.6d and prior: This is only if both marq-x and marq-y are positive)
}}
{{Option
|name=marq-y
|value=integer
|default=0
|description=Y offset from upper left corner. (0.8.6d and prior: This is only if both marq-x and marq-y are positive)
}}
{{Option
|name=marq-position
|value=integer
|default=-1 (formerly 5)
|description=Marquee position: 0=center, 1=left, 2=right, 4=top, 8=bottom, you can also use combinations of these values, eg 6 = top-right. (0.8.6d and prior: This is only used if marq-x or marq-y are negative)
}}
{{Option
|name=marq-opacity
|value=integer
|min=0
|max=255
|default=255
|description=Marquee opacity. 0 is transparent, 255 is fully opaque
}}
{{Option
|name=marq-color<span id="marq-color"></span>
|value=integer
|default=0xFFFFFF
|description=Color<sup>('''[[#appendix_marq-color|key]]''')</sup> of the text that will be rendered on the video. This must be an hexadecimal (like HTML colors). The first two chars are for red, then green, then blue. Use the decimal value of the HTML color code.
}}
{{Option
|name=marq-size
|value=integer
|min=0
|max=4096
|default=0 (formerly -1)
|description=Font size in pixels. 0 uses the default font size (formerly represented by -1)
}}
{{Option
|name=marq-timeout
|value=integer
|default=0
|description=Number of milliseconds the marquee must remain displayed. 0 means forever
}}
{{Option
|name=marq-refresh
|value=integer
|default=1000
|description=Number of milliseconds between string updates. This is mainly useful when using meta data or time format string sequences
}}</onlyinclude>

== Examples ==

Example command line use '''(VLC 2.0.0 and newer)''':
 {{%}} vlc --sub-source="marq{marquee=test,color=0xFFFF00}" somevideo.avi
This example displays yellow ''test'' text in the top left corner of video

Example command line use '''(VLC 0.9.0 - 1.1.13)''':
 {{$}} vlc --sub-filter 'marq{marquee=$t ($P%%),color=16776960}:marq{marquee=%H:%M:%S,position=6}' somevideo.avi
This command line will show the stream's title (<code>$t</code>) and current position (<code>$P</code>) in the upper left corner and the current time in the upper right corner. The <u>''single''</u> quotes <code>'</code> enclose our <code>$</code> characters to prevent them from being interpreted as Bash variables.<br />
On windows the command line would be:
 C:\Program Files\VideoLAN\VLC>vlc.exe --sub-filter=marq{marquee=$t ($P%%),color=16776960}:marq{marquee=%H:%m%s,position=6} somevideo.avi

Example command line '''(All versions including VLC 0.8.6d and prior)''':
 {{%}} vlc --sub-filter=marq --marq-marquee="Obvious Watermark" --marq-position=0 --marq-size=50 --marq-opacity=25 --marq-color=32768 somevideo.avi
This command will show centered transparent green text. Text sized too large to fit the video window will not appear, and may crash VLC.

=== time ===
The {{docmod|time}} module has different command-lines than the marq module. This not-functional command snippet overlays a white 12-point time display in the lower left of an input stream or video:

'''time:'''
 % vlc input_stream --sub-filter=time --time-format %Y-%m-%d,%H:%M:%S --time-position 9 --time-color 16777215 --time-size 12

'''marq equivalent:'''
 % vlc input_stream '--sub-source=marq{marquee="%Y-%m-%d,%H:%M:%S",position=9,color=0xFFFFFF,size=12}'

'''marq equivalent (long form):'''
 % vlc input_stream --sub-source=marq --marq-marquee="%Y-%m-%d,%H:%M:%S" --marq-position=9 --marq-color=0xFFFFFF --marq-size=12

'''additional marq example:'''
 % vlc input_stream '--sub-source=marq{marquee="%c (Week %V)",color=0xFF0000,opacity=216,size=16,position=4,timeout=500,refresh=1000}'
This overlays a 25%-transparent flashing red 16-point locale-dependent time representation with week number at the top of the input stream or video.

== Gallery ==
<gallery>
File:Marq demonstration - VLC 3.0.6 Linux.png|Marq can be chained, allowing several marquees to be displayed at the same time.|alt=Marq can be chained, allowing several marquees to be displayed at the same time. Nine positions and text colours are shown against a black background.
</gallery>

== See also ==
* [[Documentation:Format String]]
* [[Documentation:Modules/rss]]

== Source code ==
* {{VLCSourceFile|modules/spu/marq.c}}

== Appendix ==
<div class="plainlist">
*^ [[#marq-color|--marq-color]]<span id="appendix_marq-color"></span>
</div>
{{Colour mapping}}

{{Documentation footer}}