Text: Simple Video Filter

shotcut · September 2, 2019, 9:58pm

Introduction

The Text: Simple filter in Shotcut lets you overlay dynamic text onto your video. This text can be customized using keywords that are replaced with specific information about the clip or system.

Keywords

Keywords are enclosed in hash symbols (#). For example, #timecode# represents the frame’s timecode.
Supported keywords:
- #timecode# or #smpte_df#: SMPTE drop-frame timecode of the frame.
- #smpte_ndf#: SMPTE non-drop-frame timecode of the frame.
- #frame#: Frame number of the frame.
- #filedate#: Modification date of the file (GMT).
- #localfiledate#: Modification date of the file (adjusted for local time zone).
- #localtime#: Current system date and time.
- #resource#: Full file name with path of the source file.
- #filename#: File name without the path.
- #basename#: File name without the extension.
- #createdate#: Creation date of the source file. Set in the playlist clip, otherwise defaults to file modification date.
- #meta.<field>#: Accesses metadata properties for file based clips.

Formatting Time-based Keywords

Time-based keywords (#createdate#, #filedate#, #localfiledate#, and #localtime#) can be formatted using the strftime function.
Add the desired strftime format string after the keyword, separated by a non-# delimiter.
- #localtime %I:%M:%S %p# displays the time in 12-hour format with AM/PM.
- Refer to the strftime documentation for format specifiers.

Using Metadata Properties

Use #meta.<field># to include properties from the “Properties > Metadata” section.
Example
- #meta.media.0.codec.frame_rate# fps
- displays the frame rate followed by “fps”

The best way to see what metadata properties are available for a clip is to open the project file (.mlt) in a text editor and look for the section that applies to that clip. Here is an example section:

  <chain id="chain0" out="00:10:34.520">
    <property name="length">00:10:34.560</property>
    <property name="eof">pause</property>
    <property name="resource">bbb_sunflower_1080p_60fps_normal.mp4</property>
    <property name="mlt_service">avformat-novalidate</property>
    <property name="meta.media.nb_streams">3</property>
    <property name="meta.media.0.stream.type">video</property>
    <property name="meta.media.0.stream.frame_rate">60</property>
    <property name="meta.media.0.stream.sample_aspect_ratio">0</property>
    <property name="meta.media.0.codec.width">1920</property>
    <property name="meta.media.0.codec.height">1080</property>
    <property name="meta.media.0.codec.rotate">0</property>
    <property name="meta.media.0.codec.pix_fmt">yuv420p</property>
    <property name="meta.media.0.codec.sample_aspect_ratio">1</property>
    <property name="meta.media.0.codec.colorspace">709</property>
    <property name="meta.media.0.codec.name">h264</property>
    <property name="meta.media.0.codec.long_name">H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10</property>
    <property name="meta.media.0.codec.bit_rate">4001453</property>
    <property name="meta.attr.0.stream.creation_time.markup">2013-12-16T17:59:32.000000Z</property>
    <property name="meta.attr.0.stream.handler_name.markup">GPAC ISO Video Handler</property>
    <property name="meta.attr.0.stream.vendor_id.markup">[0][0][0][0]</property>
    <property name="meta.media.1.stream.type">audio</property>
    <property name="meta.media.1.codec.sample_fmt">fltp</property>
    <property name="meta.media.1.codec.sample_rate">48000</property>
    <property name="meta.media.1.codec.channels">2</property>
    <property name="meta.media.1.codec.name">mp3float</property>
    <property name="meta.media.1.codec.long_name">MP3 (MPEG audio layer 3)</property>
    <property name="meta.media.1.codec.bit_rate">160000</property>
    <property name="meta.attr.1.stream.creation_time.markup">2013-12-16T17:59:37.000000Z</property>
    <property name="meta.attr.1.stream.handler_name.markup">GPAC ISO Audio Handler</property>
    <property name="meta.attr.1.stream.vendor_id.markup">[0][0][0][0]</property>
    <property name="meta.media.2.stream.type">audio</property>
    <property name="meta.media.2.codec.sample_fmt">fltp</property>
    <property name="meta.media.2.codec.sample_rate">48000</property>
    <property name="meta.media.2.codec.channels">6</property>
    <property name="meta.media.2.codec.name">ac3</property>
    <property name="meta.media.2.codec.long_name">ATSC A/52A (AC-3)</property>
    <property name="meta.media.2.codec.bit_rate">320000</property>
    <property name="meta.attr.2.stream.creation_time.markup">2013-12-16T17:59:37.000000Z</property>
    <property name="meta.attr.2.stream.handler_name.markup">GPAC ISO Audio Handler</property>
    <property name="meta.attr.2.stream.vendor_id.markup">[0][0][0][0]</property>
    <property name="meta.attr.major_brand.markup">isom</property>
    <property name="meta.attr.minor_version.markup">1</property>
    <property name="meta.attr.compatible_brands.markup">isomavc1</property>
    <property name="meta.attr.creation_time.markup">2013-12-16T17:59:32.000000Z</property>
    <property name="meta.attr.title.markup">Big Buck Bunny, Sunflower version</property>
    <property name="meta.attr.artist.markup">Blender Foundation 2008, Janus Bager Kristensen 2013</property>
    <property name="meta.attr.comment.markup">Creative Commons Attribution 3.0 - http://bbb3d.renderfarming.net</property>
    <property name="meta.attr.genre.markup">Animation</property>
    <property name="meta.attr.composer.markup">Sacha Goedegebure</property>
    <property name="seekable">1</property>
    <property name="meta.media.sample_aspect_num">1</property>
    <property name="meta.media.sample_aspect_den">1</property>
    <property name="audio_index">1</property>
    <property name="video_index">0</property>
    <property name="creation_time">2013-12-16T17:59:32</property>
    <property name="vstream">0</property>
    <property name="meta.media.frame_rate_num">60</property>
    <property name="meta.media.frame_rate_den">1</property>
    <property name="meta.media.colorspace">709</property>
    <property name="meta.media.color_trc">2</property>
    <property name="meta.media.has_b_frames">2</property>
    <property name="meta.media.width">1920</property>
    <property name="meta.media.height">1080</property>
    <property name="meta.media.aspect_ratio">1</property>
    <property name="meta.media.color_range">mpeg</property>
    <property name="astream">0</property>
    <property name="shotcut:skipConvert">0</property>
    <property name="meta.media.top_field_first">0</property>
    <property name="meta.media.progressive">1</property>
    <property name="shotcut:hash">dfeba4ae1d00efbf318db03ed65c237c</property>
    <property name="ignore_points">0</property>
    <property name="shotcut:caption">bbb_sunflower_1080p_60fps_normal.mp4</property>
    <property name="xml">was here</property>
  </chain>

This clip has a property called “meta.attr.composer.markup”. So, if we put “#meta.attr.composer.markup#” in the text filter, it displays “Sacha Goedegebure”.

Additional Notes

Escape a literal # character with \#.

MusicalBox · January 29, 2023, 12:05am

Thanks for this.
I have wondered about all the possible keywords available in the Text: Simple filter.

Is it possible to add more? For example, the #resource# keyword displays the file name with the entire file path. Personally, I’d like one that would display only the file name.

Another suggestion maybe? What would you think about a drop-down menu containing all available keywords instead of buttons? Aside from the convenience of having them all available, it would also have the advantage of reducing the horizontal space occupied by the filter settings in the panel.

brian · August 9, 2023, 2:44am

For the next release I have added:

#filename#: The filename (with extension) of the source file
#basename#: The filename (without extension) of the source file

MusicalBox · August 9, 2023, 3:00am

Thanks @brian

I personally remove most the ones already included. One reason is because the only one I occasionally use is Timecode. But the main reason is because in find that they all take too much horizontal space in the filters panel.
Do you think it would be possible to list them in a drop-down menu instead of using buttons?

brian · August 9, 2023, 3:31am

Done

MusicalBox · August 9, 2023, 3:42am

Much appreciated @brian. Thanks!

JAMTAG · December 26, 2023, 3:43pm

As a programmer I know that the answer to this question is going to be dependent on how the filter is written.

Would it be possible to instantiate a grep style way to define our own keywords?

brian · December 26, 2023, 10:40pm

A programmer? Fantastic! We would love some help.

You will have to explain more. I’m not sure I understand the request.

But the source code is here…

github.com

mltframework/mlt/blob/master/src/modules/plus/filter_dynamictext.c

/*
 * filter_dynamictext.c -- dynamic text overlay filter
 * Copyright (C) 2011-2020 Meltytech, LLC
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#include <framework/mlt.h>

This file has been truncated. show original

JAMTAG · December 27, 2023, 3:45am

Sorry Brian I haven’t worked in C since college - and I don’t think I’d want to write this in assembler.

For example: When I’m inserting a series of clips it would make things really simple if I could use the base name but then use GREP style commands to remove the sequencing numbers from the start, add puctuation, etc. Maybe the #filename could take an optional parameter of a grep string to apply?

hunterhogan · March 2, 2024, 4:10pm

Introduction:

The Text: Simple filter in Shotcut lets you overlay dynamic text onto your video. This text can be customized using keywords that are replaced with specific information about the clip or system.

Keywords:

Keywords are enclosed in hash symbols (#). For example, #timecode# represents the frame’s timecode.
Supported keywords:
- #timecode# or #smpte_df#: SMPTE drop-frame timecode of the frame.
- #smpte_ndf#: SMPTE non-drop-frame timecode of the frame.
- #frame#: Frame number of the frame.
- #filedate#: Modification date of the file (GMT).
- #localfiledate#: Modification date of the file (adjusted for local time zone).
- #localtime#: Current system date and time.
- #resource#: Full file name with path of the source file.
- #filename#: File name without the path.
- #basename#: File name without the extension.
- #createdate#: Creation date of the source file. Set in the playlist clip, otherwise defaults to file modification date.
- #meta.<attr>.<field>.<markup>#: Accesses metadata properties.

Formatting Time-based Keywords:

Time-based keywords (#createdate#, #filedate#, #localfiledate#, and #localtime#) can be formatted using the strftime function.
Add the desired strftime format string after the keyword, separated by a non-# delimiter.
- #localtime %I:%M:%S %p# displays the time in 12-hour format with AM/PM.
- Refer to the strftime documentation for format specifiers.

Using Metadata Properties:

Use #meta.<attr>.<field>.<markup># to include properties from the “Properties > Metadata” section.
<attr>: The attribute name (e.g., “media”).
<field>: The field name within the attribute (e.g., “0.codec.frame_rate”).
<markup> (optional): Customizes the property value display.
Example
- #meta.media.0.codec.frame_rate# fps
- displays the frame rate followed by “fps”

Additional Notes:

Escape a literal # character with \#.
Refer to the source code.

hunterhogan · March 2, 2024, 4:30pm

Authorship

I started writing this post using Writesonic’s Article Writer 5, but that generated text that was completely wrong, so I switched to Google Gemini. Most of the text was cribbed from humans on this forum, including:

The meta keyword
I don’t completely understand and I haven’t yet used meta, and I am nearly certain that what I wrote has errors. I changed “attr.<field>” to " “<attr>.<field>” but that might be wrong. I am perplexed by the word “markup” in “#meta.attr.<field>.markup#”. I left it in the string, but I don’t know how to use it.

Drop-down list
I noticed that the drop-down list doesn’t currently include localfiledate, localtime, or meta. Including meta would probably be a bad idea because (I think) it is an inherently incomplete keyword so it would confuse people. I’m not sure why localfiledate and localtime are not included.

Creation date and Playlist
I just realized that I meant to but forgot to include the information about using the Playlist window to change the value of createdate and I think that is useful information.

brian · March 5, 2024, 12:30am

The best way to understand the meta attributes is to open up one of your Shotcut project files (.mlt) in a text editor like Notepad. Look for the “meta” tags in the chain producers.

Here is an example from one of my project files:

  <chain id="chain0" out="00:10:34.520">
    <property name="length">00:10:34.560</property>
    <property name="eof">pause</property>
    <property name="resource">/home/brian/Videos/open_copyright_clips/bbb_sunflower_1080p_60fps_normal.mp4</property>
    <property name="mlt_service">avformat-novalidate</property>
    <property name="meta.media.nb_streams">3</property>
    <property name="meta.media.0.stream.type">video</property>
    <property name="meta.media.0.stream.frame_rate">60</property>
    <property name="meta.media.0.stream.sample_aspect_ratio">0</property>
    <property name="meta.media.0.codec.width">1920</property>
    <property name="meta.media.0.codec.height">1080</property>
    <property name="meta.media.0.codec.rotate">0</property>
    <property name="meta.media.0.codec.pix_fmt">yuv420p</property>
    <property name="meta.media.0.codec.sample_aspect_ratio">1</property>
    <property name="meta.media.0.codec.colorspace">709</property>
    <property name="meta.media.0.codec.name">h264</property>
    <property name="meta.media.0.codec.long_name">H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10</property>
    <property name="meta.media.0.codec.bit_rate">4001453</property>
    <property name="meta.attr.0.stream.creation_time.markup">2013-12-16T17:59:32.000000Z</property>
    <property name="meta.attr.0.stream.handler_name.markup">GPAC ISO Video Handler</property>
    <property name="meta.attr.0.stream.vendor_id.markup">[0][0][0][0]</property>
    <property name="meta.media.1.stream.type">audio</property>
    <property name="meta.media.1.codec.sample_fmt">fltp</property>
    <property name="meta.media.1.codec.sample_rate">48000</property>
    <property name="meta.media.1.codec.channels">2</property>
    <property name="meta.media.1.codec.name">mp3float</property>
    <property name="meta.media.1.codec.long_name">MP3 (MPEG audio layer 3)</property>
    <property name="meta.media.1.codec.bit_rate">160000</property>
    <property name="meta.attr.1.stream.creation_time.markup">2013-12-16T17:59:37.000000Z</property>
    <property name="meta.attr.1.stream.handler_name.markup">GPAC ISO Audio Handler</property>
    <property name="meta.attr.1.stream.vendor_id.markup">[0][0][0][0]</property>
    <property name="meta.media.2.stream.type">audio</property>
    <property name="meta.media.2.codec.sample_fmt">fltp</property>
    <property name="meta.media.2.codec.sample_rate">48000</property>
    <property name="meta.media.2.codec.channels">6</property>
    <property name="meta.media.2.codec.name">ac3</property>
    <property name="meta.media.2.codec.long_name">ATSC A/52A (AC-3)</property>
    <property name="meta.media.2.codec.bit_rate">320000</property>
    <property name="meta.attr.2.stream.creation_time.markup">2013-12-16T17:59:37.000000Z</property>
    <property name="meta.attr.2.stream.handler_name.markup">GPAC ISO Audio Handler</property>
    <property name="meta.attr.2.stream.vendor_id.markup">[0][0][0][0]</property>
    <property name="meta.attr.major_brand.markup">isom</property>
    <property name="meta.attr.minor_version.markup">1</property>
    <property name="meta.attr.compatible_brands.markup">isomavc1</property>
    <property name="meta.attr.creation_time.markup">2013-12-16T17:59:32.000000Z</property>
    <property name="meta.attr.title.markup">Big Buck Bunny, Sunflower version</property>
    <property name="meta.attr.artist.markup">Blender Foundation 2008, Janus Bager Kristensen 2013</property>
    <property name="meta.attr.comment.markup">Creative Commons Attribution 3.0 - http://bbb3d.renderfarming.net</property>
    <property name="meta.attr.genre.markup">Animation</property>
    <property name="meta.attr.composer.markup">Sacha Goedegebure</property>
    <property name="seekable">1</property>
    <property name="meta.media.sample_aspect_num">1</property>
    <property name="meta.media.sample_aspect_den">1</property>
    <property name="audio_index">1</property>
    <property name="video_index">0</property>
    <property name="creation_time">2013-12-16T17:59:32</property>
    <property name="vstream">0</property>
    <property name="meta.media.frame_rate_num">60</property>
    <property name="meta.media.frame_rate_den">1</property>
    <property name="meta.media.colorspace">709</property>
    <property name="meta.media.color_trc">2</property>
    <property name="meta.media.has_b_frames">2</property>
    <property name="meta.media.width">1920</property>
    <property name="meta.media.height">1080</property>
    <property name="meta.media.aspect_ratio">1</property>
    <property name="meta.media.color_range">mpeg</property>
    <property name="astream">0</property>
    <property name="shotcut:skipConvert">0</property>
    <property name="meta.media.top_field_first">0</property>
    <property name="meta.media.progressive">1</property>
    <property name="shotcut:hash">dfeba4ae1d00efbf318db03ed65c237c</property>
    <property name="ignore_points">0</property>
    <property name="shotcut:caption">bbb_sunflower_1080p_60fps_normal.mp4</property>
    <property name="xml">was here</property>
  </chain>

This clip has a property called “meta.attr.composer.markup”. So, if I put “#meta.attr.composer.markup#” in the text filter, it displays “Sacha Goedegebure”

I hope that helps.

brian · March 5, 2024, 12:32am

Yes. I agree.

I didn’t include them because they depend on the timezone of the computer that is using Shotcut. So different users would get different results depending on where they live, or what their timezone is set to.

Jowan_Spooner · July 25, 2024, 10:57pm

Curious whether it’s also somehow possible to insert the shotcut:... properties? Especially shotcut:caption and shotcut:comment would be cool imo!

brian · July 26, 2024, 8:06pm

It’s an interesting idea. But, unfortunately, not possible, currently.

Jowan_Spooner · July 26, 2024, 8:39pm

I see! It’s not something I urgently need, but something that felt more natural to me, then the file name, because I tend to leave the file names as they come (not very discriptive stuff like 00160.mts) and then rename the files in shotcut. Well, maybe it becomes possible one day

Cookie_Undercover · August 19, 2024, 10:15pm

How do I edit the length of the text? I don’t see any way to I tried using different time codes to see if I could make one section of text disappear while another one appears and it didn’t work.

This is the best I’ve been able to do, but both of the lines show up.

shotcut · August 20, 2024, 12:41am

This filter does not support timed text or keyframes on the text itself. The next version 24.08 for which there is a beta/release-candidate has a Subtitles feature with a filter to overlay the subtitles that will do this.

Eva_Stadnikov · August 31, 2024, 2:55pm

Hello. I can’t find the ability to batch apply the simple text filter to photos. Is there such an option?