Difference between revisions of "Documentation:Modules/marq"

From VideoLAN Wiki
Jump to navigation Jump to search
(→‎Time: New section with time command-line equivalents and an additional example)
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{Module|name=marq|type=Video subfilter|first_version=0.8.0|description=Overlays text on the video}}
+
{{Module|name=marq|type=Video sub-filter|first_version=0.8.0|description=Overlays text on the video|sc=marq|sc2=time}}
  
−
The marq subfilter can be used to display text on a video. The [[Documentation:Modules/time|time]] filter was merged with this filter in version 0.9.0.
+
The ''marq'' subtitle filter can be used to display text on a video. The {{docmod|time}} filter was merged with this filter in version 0.9.0, adding time [[Documentation:Format String|format string]] recognition. There are two methods of specifying position: coordinate and (since VLC 0.9.0) [[#marq-position|numbered positions]].
  
 
== Options ==
 
== Options ==
−
 
+
<onlyinclude>{{Option
−
{{Option
 
 
|name=marq-marquee
 
|name=marq-marquee
 
|value=string
 
|value=string
 
|default=VLC
 
|default=VLC
−
|description=Marquee text to display. Since VLC version 0.9.0 you can use [[Documentation:Play_HowTo/Format_String|format strings]] to display time information
+
|description=Marquee text to display.
 
}}
 
}}
−
 
 
{{Option
 
{{Option
 
|name=marq-file
 
|name=marq-file
 
|value=string
 
|value=string
−
|description=File to read the marquee text from
+
|default=NULL
−
}}
+
|description=File to read the marquee text from.
−
 
+
}}<noinclude>
 +
=== Position ===
 +
</noinclude>
 
{{Option
 
{{Option
 
|name=marq-x
 
|name=marq-x
 
|value=integer
 
|value=integer
−
|default=0 (0.8.6d and prior: -1)
+
|default=0
−
|description=X offset from upper left corner. (0.8.6d and prior: This is only if both marq-x and marq-y are positive)
+
|description=X offset, from the left screen edge.
 
}}
 
}}
−
 
 
{{Option
 
{{Option
 
|name=marq-y
 
|name=marq-y
 
|value=integer
 
|value=integer
 
|default=0
 
|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)
+
|description=Y offset, down from the top.
 
}}
 
}}
−
 
 
{{Option
 
{{Option
−
|name=marq-position
+
|name=marq-position<span id="marq-position"></span>
 
|value=integer
 
|value=integer
−
|default=-1 (formerly 5)
+
|default=-1
−
|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)
+
|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.
−
}}
+
}}<noinclude>
−
 
+
=== Font ===
−
{{Option
+
</noinclude>{{Option
 
|name=marq-opacity
 
|name=marq-opacity
 
|value=integer
 
|value=integer
Line 45: Line 43:
 
|max=255
 
|max=255
 
|default=255
 
|default=255
−
|description=Marquee opacity. 0 is transparent, 255 is fully opaque
+
|description=Opacity (inverse of transparency) of overlaid text. 0 {{=}} transparent, 255 {{=}} totally opaque.
 
}}
 
}}
−
 
 
{{Option
 
{{Option
−
|name=marq-color
+
|name=marq-color<span id="marq-color"></span>
 
|value=integer
 
|value=integer
−
|default=-268435456 (formerly 16777215 (0xFFFFFF, white))
+
|select={ 0x000000, 0x808080, 0xC0C0C0, 0xFFFFFF, 0x800000, 0xFF0000, 0xFF00FF, 0xFFFF00, 0x808000, 0x008000, 0x008080, 0x00FF00, 0x800080, 0x000080, 0x0000FF, 0x00FFFF }
−
|description=Marquee color. Use the decimal value of the HTML color code
+
|default=0xFFFFFF
 +
|description=Color<noinclude><sup>('''[[#appendix_marq-color|key]]''')</sup></noinclude> 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.
 
}}
 
}}
−
 
 
{{Option
 
{{Option
 
|name=marq-size
 
|name=marq-size
Line 60: Line 57:
 
|min=0
 
|min=0
 
|max=4096
 
|max=4096
−
|default=0 (formerly -1)
+
|default=0
−
|description=Font size in pixels. 0 uses the default font size (formerly represented by -1)
+
|description=Font size, in pixels. 0 uses the default font size.
−
}}
+
}}<noinclude>
−
 
+
=== Misc ===
−
{{Option
+
</noinclude>{{Option
 
|name=marq-timeout
 
|name=marq-timeout
 
|value=integer
 
|value=integer
 
|default=0
 
|default=0
−
|description=Number of milliseconds the marquee must remain displayed. 0 means forever
+
|description=Number of milliseconds the marquee must remain displayed. 0 means forever.
 
}}
 
}}
−
 
 
{{Option
 
{{Option
 
|name=marq-refresh
 
|name=marq-refresh
 
|value=integer
 
|value=integer
 
|default=1000
 
|default=1000
−
|description=Number of milliseconds between string updates. This is mainly useful when using meta data or time format string sequences
+
|description=Number of milliseconds between string updates. This is mainly useful when using meta data or time [[Documentation:Format String|format string]] sequences.
−
}}
+
}}</onlyinclude>
  
 
== Examples ==
 
== Examples ==
 +
 +
=== Versions 2.0 and later ===
  
 
Example command line use '''(VLC 2.0.0 and newer)''':
 
Example command line use '''(VLC 2.0.0 and newer)''':
−
  % '''vlc --sub-source="marq{marquee=test,color=16776960} somevideo.avi'''
+
  {{%}} vlc '--sub-source=marq{marquee="%Y-%m-%d,%H:%M:%S",position=9,color=0xFFFF00,size=12}' somevideo.avi
−
:This example displays yellow ''test'' text in the top left corner of video
+
This example displays the current date and time in yellow 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'''
 
−
% '''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 ($t) and current position ($P) in the upper left corner and the current time in the upper right corner. Note that we have to escape $ characters when running this from command line in UNIX shells (this is why we use \$ instead of $). The second line uses single quotes to delimit the string so we don't need to escape the $ character.
 
−
: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:'''
+
The equivalent long form would be;
−
  % vlc input_stream --sub-filter=time --time-format %Y-%m-%d,%H:%M:%S --time-position 9 --time-color 16777215 --time-size 12
+
  {{%}} vlc --sub-source=marq --marq-marquee="%Y-%m-%d,%H:%M:%S" --marq-position=9 --marq-color=0xFFFFFF --marq-size=12 somevideo.avi
  
−
'''marq equivalent:'''
+
=== Versions 0.9.0 to 1.1.13 ===
−
  % vlc input_stream '--sub-source=marq{marquee="%Y-%m-%d,%H:%M:%S",position=9,color=16777215,size=12}'
+
  {{$}} vlc --sub-filter 'marq{marquee=$t ($P%%),color=0xFFFF00}: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:
 +
{{Prompt|cmd}} {{Path to VLC|windows}} --sub-filter=marq{marquee=$t ($P%%),color=0xFFFF00}:marq{marquee=%H:%m%s,position=6} somevideo.avi
  
−
'''marq equivalent (long form):'''
 
−
% vlc input_stream --sub-source=marq --marq-marquee="%Y-%m-%d,%H:%M:%S" --marq-position=9 --marq-color=16777215 --marq-size=12
 
  
−
'''additional marq example:'''
+
== Gallery ==
−
% vlc input_stream '--sub-source=marq{marquee="%c (Week %V)",color=16711680,opacity=216,size=16,position=4,timeout=500,refresh=1000}'
+
<gallery>
−
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.
+
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 ==
 
== See also ==
−
* [[Documentation:Format_String]]
+
* [[Documentation:Format String]]
 
* [[Documentation:Modules/rss]]
 
* [[Documentation:Modules/rss]]
  
 
== Source code ==
 
== Source code ==
 
* {{VLCSourceFile|modules/spu/marq.c}}
 
* {{VLCSourceFile|modules/spu/marq.c}}
 +
* {{VLCSourceFile|p=vlc/vlc-0.8.git|modules/video_filter/marq.c}}
  
−
{{Image requested}}
+
== Appendix ==
 +
<div class="plainlist">
 +
*^ [[#marq-color|--marq-color]]<span id="appendix_marq-color"></span>
 +
</div>
 +
{{Colour mapping}}
  
 
{{Documentation footer}}
 
{{Documentation footer}}

Latest revision as of 14:44, 10 May 2020

Module: marq
Type Video sub-filter
First VLC version 0.8.0
Last VLC version -
Operating system(s) all
Description Overlays text on the video
Shortcut(s) marq, time

The marq subtitle filter can be used to display text on a video. The time filter was merged with this filter in version 0.9.0, adding time format string recognition. There are two methods of specifying position: coordinate and (since VLC 0.9.0) numbered positions.

Options

  • marq-marquee <string> : Marquee text to display. default value: VLC
  • marq-file <string> : File to read the marquee text from. default value: NULL

Position

  • marq-x <integer> : X offset, from the left screen edge. default value: 0
  • marq-y <integer> : Y offset, down from the top. default value: 0
  • marq-position <integer> : Marquee position: 0=center, 1=left, 2=right, 4=top, 8=bottom, you can also use combinations of these values, eg 6 = top-right. default value: -1

Font

  • marq-opacity <integer [0 .. 255]> : Opacity (inverse of transparency) of overlaid text. 0 = transparent, 255 = totally opaque. default value: 255
  • marq-color <integer> { 0x000000, 0x808080, 0xC0C0C0, 0xFFFFFF, 0x800000, 0xFF0000, 0xFF00FF, 0xFFFF00, 0x808000, 0x008000, 0x008080, 0x00FF00, 0x800080, 0x000080, 0x0000FF, 0x00FFFF } : Color(key) 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. default value: 0xFFFFFF
  • marq-size <integer [0 .. 4096]> : Font size, in pixels. 0 uses the default font size. default value: 0

Misc

  • marq-timeout <integer> : Number of milliseconds the marquee must remain displayed. 0 means forever. default value: 0
  • marq-refresh <integer> : Number of milliseconds between string updates. This is mainly useful when using meta data or time format string sequences. default value: 1000

Examples

Versions 2.0 and later

Example command line use (VLC 2.0.0 and newer): 

% vlc '--sub-source=marq{marquee="%Y-%m-%d,%H:%M:%S",position=9,color=0xFFFF00,size=12}' somevideo.avi

This example displays the current date and time in yellow in the top left corner of video.

The equivalent long form would be; 

% vlc --sub-source=marq --marq-marquee="%Y-%m-%d,%H:%M:%S" --marq-position=9 --marq-color=0xFFFFFF --marq-size=12 somevideo.avi

Versions 0.9.0 to 1.1.13

$ vlc --sub-filter 'marq{marquee=$t ($P%%),color=0xFFFF00}:marq{marquee=%H:%M:%S,position=6}' somevideo.avi

This command line will show the stream's title ($t) and current position ($P) in the upper left corner and the current time in the upper right corner. The single quotes ' enclose our $ characters to prevent them from being interpreted as Bash variables.
On Windows the command line would be: 

> "%PROGRAMFILES%\VideoLAN\VLC\vlc.exe" --sub-filter=marq{marquee=$t ($P%%),color=0xFFFF00}:marq{marquee=%H:%m%s,position=6} somevideo.avi


Gallery

  • 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.

    Marq can be chained, allowing several marquees to be displayed at the same time.

See also

Source code

Appendix

Colour key
Sample Colour Hex code
Black 0x000000
Gray 0x808080
Silver 0xC0C0C0
White 0xFFFFFF
Maroon 0x800000
Red 0xFF0000
Fuchsia 0xFF00FF
Yellow 0xFFFF00
Olive 0x808000
Green 0x008000
Teal 0x008080
Lime 0x00FF00
Purple 0x800080
Navy 0x000080
Blue 0x0000FF
Aqua 0x00FFFF
This page is part of official VLC media player Documentation (User Guide • Streaming HowTo • Hacker Guide • Modules)
Please read the Documentation Editing Guidelines before you edit the documentation
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Retrieved from "https://wiki.videolan.org/index.php?title=Documentation:Modules/marq&oldid=62049"