VLyriCVLyric on WINE

Display lyrics and other text overlays using VLC

                        Installation         Usage         Changes       Download       Feedback

VLC, that Swiss army knife of video,  has a "Marquee display" plugin that lays text over the video.  This program makes use of VLC's "Remote Control" TCP interface to more easily control the display of text, switch video sources, and send other commands to VLC.

Motivation for this project

In 2005 I was asked to serve as the technology specialist for the Longview, WA stake of The Church of Jesus Christ of Latter-day Saints.  Part of my responsibilities include utilizing audio/video technology to ensure that all members are able to adequately participate in larger gatherings that are held periodically.  Whereas little assistance is needed for a cozy congregation of 200 in the chapel, when that swells to 1,000 or more and people gather in the gym, classrooms around the the building, and even other locations, technology becomes much more important.

Obviously, audio is important, so you can hear the speakers.  Video allows remote participants to be able to see the speaker and others in the chapel, and helps them to feel more a part of the service.  Another practical aspect of video is that, particularly when someone is hard of hearing, the ability to "lipread" can make the audio more intelligible.  (Thus, the importance of low-latency video in local applications; having a 300ms delay hurts, rather than helps, in this regard.)  When all of the participants are in the same room  as the "action" -- merely far away from the speaker -- a single fixed camera is fine.  However, when the telecast is the only link, staring at a big talking head can get tiring, and it is very nice to be able to switch camera angles for both variety and a better view of other activities (for example, the choir performing).

Hymn singing is particularly challenging.  The most basic setup allows you to either have video or a lyric display, but not both; or, paper copies of the music are provided.  Neither of these is ideal when you're in a location isolated from the maincongregation, and don't have the quality of audio and visual feedback that you do in a live setting.  It's much more convenient to be able to see both the music director and the lyrics simultaneously.  Having the lyrics clearly displayed just-in-time as an on-screen text overlay (while providing clear audio) is perfect, allowing everyone to enjoy singing, rather than having people struggle to figure out if they're singing the right words at the right time and feeling like fools.  The same display could be used to identify speakers, display scriptures and quotes.  Done right, the remote participants can have an experience that's nearly as good -- in some ways even better -- than those sitting in front-row seats in the chapel.

Summary of core requirements

Other available hardware/software

Were money no object, a professional-quality video system including multi-channel video mixers using chroma keying for the text would be in order. (analog when I started; now I want an array of hi-def cameras using IEEE-1394 over Ethernet!)  With the conversion of many broadcast television stations from analog to digital, prices on used analog gear are dropping, but it's still in demand.

There are many products out there for displaying lyrics on a computer display. The list includes some fine open-source offerings like LyriCue and OpenLP.  The biggest disadvantage of most of these is that they're verse-oriented rather than line-oriented.  They seem to be designed for a high-resolution display dedicated to just presenting the lyrics, and all of the preconfiguration displays an entire verse at a time in small print.  Until recently, most of them couldn't display the text over live video by themselves.  Great for amultimedia show in a big auditorium, but not for the kind of low-key display for remote broadcast that I was looking for.

The first solution

Though I was fairly ignorant of the technicalities of popular computer video display techniques, I had previously made a discovery that, annoying to most people, was crucial to my success:  You can't make screenshots of video.

I was running Windows XP with a fairly nice (when it was new) nVidia video card.  Every time I tried to take a screenshot of video playing, the resulting screenshot showed a plain blackrectangle instead of video.  That's disappointing!  The  effect when you happen to move that screenshot over a playing video, however is magical: any time part of that area covers the video, it acts as a "window" through which the video appears!  Yes, I had discovered video overlays.

I manually assembled slides using OpenOffice.org.  Because I wanted each slide to show both the current line of the song and (in smaller text) the next, each line had to appear twice.  It was a fairly laborious process to format the slides nicely, though I got to where I could do it pretty efficiently after more experience.

After using the eyedropper tool in Paint Shop Pro 4 to determine which flavor of black was being used at any given time for the overlay, I set the background color of the slides to that; thus it would be black normally, but transparent when over video.  I used the "lite" version of ChrisTV with a $10 add-on to display the video.  I liked that I could have it either full-screen or quickly (and mostly glitch-free) switch to clean-looking windows of various sizes, allowing me to have the director displayed in a window above with text below if I wanted -- though as time went on, I eventually dropped this entirely in favor of full-screen video.

The presentation is displayed on one monitor, while another is used for control.  The VGA signal is actually split, feeding a monitor, a projector behind me, and a scan converter that is then fed into an RF modulator for distribution elsewhere.  For video switching, I fed multiple cameras into an Osprey BT848-based capture card, and used the Osprey control panel app to switch inputs on the card. The machine actually has multiple capture cards; each camera is fed both into one of the inputs on the live card as well as its own dedicated card, where I use multiple instances of VirtualDub, of all things, to provide camera preview windows for me. 

Zoom/Focus controlI used an assortment of cameras, mostly old VHS camcorders.  My main camera is a small security camera that I mount on a telescope tripod with a clock drive; I can then use the remote control for the clock drive to pan the camera.  I also created a custom remote control unit for the camera that allows me to simultaneously zoom and focus with my other hand.

The problem

The biggest problem was that the solution was hardware & software-specific.  I had a hard time finding other computers (or video cards) that I could use the technique with, and not all video players were as kind.   The computer wasn't the fastest on the planet, and in addition to the constant tolerable-but-noticable lag on the video, every time I switched slides, it paused the video briefly, making the chorister's arm jerk.  Something that was more flexible was desirable -- especially after the hard drives died and I had to rebuild the machine.  ChrisTV, who forced updates, decided to remove critical features from the lite version (I'd been backdating the system for a while avoid the "upgrade") and not being able to obtain the plugin for the old version anymore, aside from the fact that the pro version wasn't stable for some reason, I didn't really feel like rewarding them for crippling what I had paid for. 

The new solution

With only a week before I needed to begin my normal preparations, I started shopping around for alternatives.  Still highly unsatisfied with existing software,  I began to wonder about VLC, since it was cross-platform, very flexible, and did subtitles, etc.  Upon discovery of its Marquee plugin and command-line control ability, I began experimenting.  With a hopefull heart, I began growing this program from a proof-of-concept, slowly adding features as it became clearer that it could work.  I briefly considered using this project as an excuse to improve my Python programming skills, but the need for rapid development caused me to fall back to Delphi, which I knew would easily do what I needed, and not require the installation of an interpreter or any other software to run the program.


With less than a day to go, and all of my presentation material already entered and tested, I finally tested for the first time with a good-quality live camera.  (Previously I'd used a really old webcam, videos, and my cell phone's web browser for video sources as I'd tested things).  To my horror, I found that the video lagged by about 600ms!  After research and experimentation, I found that by eliminating the sound (which I wasn't using anyway) and adjusting the dshow-caching parameter, I could reduce the lag to about 250ms.

VLC 2.0 had recently been released, and I tried it out.  The text looked much nicer than older versions.  It was no longer limited to the resolution of the video, but would be displayed at full screen resolution; also, the text had a nice drop shadow.  (See screenshots comparing old & new) The overall effect was smoother and richer.  However, I found that I could reduce the lag by another 150ms by using V4L2 on my newer Linux machine instead of DirectShow on the old XP box.  I couldn't drop the caching below 30ms (hmm, about one NTSC frame?), or it would tend to freeze the image (esp. in full-screen mode) waiting for data.  A 40-50ms cache value worked fine.  Since VLC 2 isn't "out of the box" compatible with the older Ubuntu release I was running, I decided to sacrifice the richer text to achieve the reduced latency; lip sync was much better than it had been under Windows.

Installing VLyriC

VLyric runs as a single Windows executable.  I recommend that you place it in a dedicated directory; it will create default configuration files, and it expects all of its configuration material to be in the same directory as the program.  This aids portablity; simply copy the entire directory to a USB drive, and run it from any machine you like.

Hardware/OS Compatibility

Because VLyric uses a TCP connection to control VLC, the two need not be on the same machine.  Any machine that runs VLC well should perform no differently when controlled by VLyriC.

I have only tested the program on Windows XP and Ubuntu 11.04, but I expect that it will run fine on any version of MS Windows from 2000 onward, and any OS that fully supports WINE of similar, er, vintage. 

A picture of VLyriC in actionUsing the program

VLyriC was developed very quickly, and hasn't yet had polish applied.  There is currently no in-program help file, but there are tooltips for each control.  Below is a description of the interface and a few hints to get you started.

Launch VLC

At the bottom of the form is a history of DOS commands executed.  These can be conveniently used to directly launch a copy of VLC on the local machine (only VLC for Windows, not a copy outside of a WINE environment) or copied to the clipboard to launch elsewhere.


You can't do much until you connect to a running VLC instance.  To actually see the text overlay, video must be running.

Ad-hoc Commands

A history of commands sent to VLC is retained here.  Click on a previously-sent command to recall it, optionally edit it, and re-execute.


This is simply a convenient storage of commands to initialize VLC.  Use it after first connect, and at any time afterwards.  You can maintain multiple init files; the program will remember the last one you used.


These also send commands to VLC.  Designed for switching video sources, they could be used for anything else too.  I switched cameras by adding a new playlist item with the new video source and parameters.  I found that switching inputs on the capture card could be done smoother using v4l2-ctl, but using that from VLyriC would requires a separate command channel, so fortunately the VLC playlist technique worked well enough.  I did notice that when changing to a different video device, the marquee settings would be reset back to defaults, requiring a quick hit of the Init button to eliminate the "VLC" label and set things back to where they ought to be.  As long as you stay on the same device, inputs can be changed without this occuring.

Lyric Editor

You can use multiple init files; the program will remember the last one you used.  You can load, save, and edit in this window.  Ctrl-F will allow you to find text in here.  Hit the arrow button to send your changes to the display queue and position the queue at your current line.

Display Queue

When you press the slide button, the highlighted line (or series of lines -- see next section) will be sent to VLC, and the queue will be advanced to the next line.  Pressing the upper button will back up to the previous line (or attempt to back up through multiple lines to the previous slide.  The effect on complex slides may not always be as desired).  When the "next slide" button is selected, the space bar can also be used to hit it, and the zero on the numeric keypad will back up a slide, the same as hitting the upper button.   Pressing the "<#" button will position the edit window at the current line in the display queue, making it easier to make last-minute edits.

Slide Formatting

By default, the current line of text will be sent to marquee #1, and the next line will be sent to marquee #2.  This makes for a very easy basic display of song lyrics.  As the notes above the edit window indicate, mulitple lines can be executed in one batch, allowing more control over the slide formatting.  See the sample files to see how you might display other types of infomation.  I'm using up to 3 marquees, but more could be added for complex displays.

Enhancing VLyriC

Network Broadcasting

Unfortunately, you can't directly take advantage or VLC's built-in network broadcasting capability to stream video with your text overlays.  The text overlays apparently work directly with the display module, and the video transcoding takes place before that stage, so any broadcast video will only cantain your original video source, sans overlays.

One way of getting around this would be to feed the video output of VLC's display into a 2nd capture card (on the same or another computer) that would be used as input to another VLC instance that would be responsible for encoding and broadcast. 

To encode video with text overlays without the extra capture hardware would require a display module that would create a new video source (e.g. a pseudo v4l2/directshow input device) that could be fed to a 2nd VLC instance.

On the Windows platform, there is just such a product available.  "Aczlan" on the LDS tech forums pointed me to a $30 product called VCam that creates one or more DirectShow sources, and has a VLC plugin.  (Note that at the time of this writing, the plugin only supports VLC 1.x)  Simply set your 1st VLC instance to display using the VCam module (instead of to the screen), and use VCam as the input source for your 2nd VLC instance, which handles display and broadcasting.  I verified that it works (screenshot), and even saved a 400kB H.264 test video, though VCam drove the CPUs on my test machine to saturation and the frame rate was terrible.

In any case, the extra encoding step will further increase latency, so you will need to fight to minimize this.  Note that if you're encoding audio along with it,  and your viewers are not using the sound from the in-building PA system, latency won't be bothersome, because you will still be able to ensure that the audio & video sync.

Change Log

1.0 - 03/10/2012 - Created.
2.0 - 12/14/2014 - Fork/rewrite by Caleb H. (requires .NET)

Caveats (April 2015)

VLC 2.1 broke the marquee commands (See bug report); until that issue is resolved, you should use VLC v2.0.8 or older.

Caleb posted his last v2 files right before he left on his mission, and from what he and others have told me, it may have a problem sending commands to VLC correctly. If his source code is buildable and someone identifies and can fix whatever problems are there, I'd be happy to link to an updated version; otherwise, you may need to stick to the v1 branch until 2017.


VLyriC (231k) - This is what you need to run VLyriC.
Samples (8k) - Files from its first real-life use, to help you see some of what it can do.  (Also includes a bitmap of the icon for convenient decorating of shortcuts on non-Windows systems.)
Source Code (26k) - Delphi 5 source package.


Questions, Comments, Suggestions?
Write me at vlyric@boling.us.