JAWS Scripts For VLC Media Player
Doug Lee
Last Revised May, 2024

This document describes the JAWS scripts for VLC Media Player (VLC) and provides tips for using this application with JAWS. This document can be opened from within the application via a double press of JAWSKey+F1 (or Insert+F1) when the scripts are running.

Warning: Although these scripts should work as advertised and will provide benefit to users, much more could be done for this application's usability with JAWS. Additionally, VLC itself at this writing (April, 2024) contains significant bugs that, in this script author's estimation, would adversely affect many users. It is for this latter reason that further scripting efforts for this application have been suspended. Specific bugs of note:

• Attempting to skip forward or backward in a .ogg file very often results in unexpected jumps and/or termination of play.
• In this script author's experience, use of the Ctrl+T command to jump to a specific time in the file only works correctly if a full, hh:mm:ss format, time entry is typed. If this is not done, playback usually stops.
• Skipping in several if not all file types frequently results in a short-term but multi-second period during which the playback speed of the file is lower than intended.
• There does not appear to be a way for a screen reader to discover the volume level accurately above 125, but VLC allows much higher settings.

Table of Contents

• System Requirements For JAWS Users
• Script Installation Instructions
• Key Sequences
• Script Commands and Features
• A Quick Primer On VLC Usage With JAWS
  • Setup tips
  • Common tasks and keystrokes
  • Using the Advanced Preferences Screen
  • Other Tips and Tricks
• Known Issues
• Revision History

System Requirements For JAWS Users

In addition to any system requirements for the application, the following apply for JAWS users:

• The computer should be running Windows 10 or later. Other Windows versions may work but have not been tested.
• JAWS 2018 or later should be used. The scripts will not work with or install into older JAWS versions.

Script Installation Instructions

To install these scripts on a new system:

1. Install JAWS if this has not already been done. This will require administrative privileges on the computer.
2. Run JAWS as the user for whom the scripts are to be installed. This and the following steps must be performed for each user of the computer who will be using JAWS with these scripts.
3. Download and run, or run directly, the installer for these scripts; and follow the on-screen directions. Be sure to install the scripts in the currently running JAWS version if a JAWS version list is presented.
4. To verify successful installation, type Insert+Q from within the application. Part of the JAWS spoken response should be a revision number. If you do not hear a revision number, the scripts are not correctly loaded. In some cases, restarting JAWS may fix this issue.

Key Sequences

These scripts incorporate commands that consist of sequences of keystrokes, all beginning with a common prefix, or "command keystroke." This approach allows many script commands without the risk of conflicting with application keystrokes. See the "Multi-Key Command Sequences" section of the "Common Script Elements" document for further details, including how to explore the available script commands (similar to exploring a menu system), and how to change the Command keystroke if necessary.

By default, the Command keystroke for these scripts is [. This document may refer to this keystroke as [ or Command; so, for example, [ Tab and Command Tab both refer to typing the prefix keystroke, then separately the Tab key. Some sequences may consist of more than two keystrokes, or "levels"; for example, [ d r would refer to typing [, then d, then finally r.

Script Commands and Features

These scripts provide the following commands beyond those provided by JAWS and the application:

• The sequence [ V reads the volume level and says "muted" if output is muted. Volume levels range from 0 to 125, but the VLC volume may go higher than indicated by this value.
• The sequence [ T E reads the elapsed time for the current track.
• The sequence [ T T reads the total time of the current track.
• The sequence [ T R announces the remaining time for the current track.
• JAWSKey+PgDn reads the status bar if available. The status bar can be toggled on and off in the VLC View menu (Alt+I). This command, however, will announce the status bar's contents whether visible or not. If the status bar is invisible, the information will be spoken in a slightly lower voice, or more specifically, with the JAWS message voice. See the Known Issue for reading invisible status bars for a small caveat. The status bar includes the following items, in this order:
  • The name of the playing file or stream.
  • The speed variation; "1.00x" means normal speed.
  • The elapsed or remaining time, a slash (/), and the total time in the file. If the remaining time rather than the elapsed time is shown, it will be preceded with a negative sign or dash (-).
  • If the file is protected by Digital Rights Management (DRM), an indication of this.
• JAWSKey+B, the standard JAWS command for reading a dialog in tab order, reads VLC dialogs and screens.
• JAWSKey+Q, along with announcing the active configuration name, will announce the revision number of these scripts.
• Insert+F1, typed twice in quick succession, opens this document in the default browser.

These scripts also provide the following features:

• JAWS is better at tracking the opening and closing of menus and menu bars.
• There are many improvements in JAWS' identification of controls.
  Specific field naming support

  • Many fields announce descriptions, either in place of missing names or in addition to names.
  • Tab controls announce the position and count of tabs in the control, to help avoid confusion when a screen contains more than one tab control.
  • Equalizer sliders, including the Preamp slider, announce band and dB level.
  • There is similar scripting for the sliders in the other audio effects tabs.
  • There is specific scripting for the spin boxes in the Synchronization tab.
  • When JAWS considers the PC cursor position to be outside of the VLC window, the scripts prevent the SayLine command from announcing information related to a non-VLC screen area.
• The Space bar does not speak, so it is not so disruptive as a means of pausing and resuming playback.
• Keys that move through the playing file work without extra speech. These are the Left and Right arrows by themselves, with Alt, with Shift, with Ctrl, and with Ctrl+Alt.
• Volume adjustment commands also work and without extra speech. These are the Up and Down arrows by themselves and with Ctrl.
• The scripts make JAWS report changes in how many settings pages are available during a search in the Advanced Preferences screen.

A Quick Primer On VLC Usage With JAWS

This section is meant as a quick guide, but not a replacement for VLC documentation or its built-in keystroke list.

Setup tips

• Preferences can be opened directly with Ctrl+P.
• Focus will land on one of two radio buttons: Simple, or All. Simple is preferred for this section as it presents a less complex setup interface. Left and Right arrows move between these radio buttons.
• The Preferences screen consists largely of a section selected by what would normally be a tab control, but what in VLC is a set of checkboxes. Tab past Ok and Cancel to the first checkbox, usually Interface. Left and Right arrows will now select among pages.
• The first Tab after the checkboxes may be silent. Just Tab again when this happens.
• The Interface page contains an "Allow only one instance" setting that is not checked by default. Those arriving in VLC from another alternative such as Winamp may be startled by this and may want to check this box, to prevent multiple VLC instances from running at once.
• However, the next checkbox, "Use only one instance when started from file manager," is checked by default and already prevents selection of files from Windows Explorer from launching multiple VLC instances.
• In the Audio page, the Device combo box is where you select the default output device for VLC. There is also an Audio menu available on the main VLC screen and activated with Alt+A, where another Device option can be found. However, changes in that location will reset to the default from Preferences when VLC is closed and restarted.
• You can disable all video rendering if you only need audio output, to improve performance and efficiency. Do this with the first checkbox in the Video page.
• The Hotkeys page is where to find all the key assignments, both in-app and global, offered by VLC. These appear in a Tree control that has three columns. Up and Down arrows move among key assignment rows, and Left and Right move among columns. In order, the columns contain the action, the keystroke that works when focus is in VLC, and any keystroke that occurs regardless of which app is in focus. This tree of keystrokes is a very good place to start learning VLC's keyboard interface.

Common tasks and keystrokes

These keystrokes work when focus is in VLC:

• Ctrl+O opens a file selector, as in many apps, for selecting a file to play. There are several other ways to select something to play, all of which can be found in the Media menu (Alt+M).
• Space pauses and resumes playback, and S stops.
• With the scripts running, the sequences [ T E, [ T R, and [ T T will report the elapsed, remaining, and total times of the current track, respectively.
• The scripted JAWS command JAWSKey+PgDn will read the contents of the status bar, whether displayed on screen or not. This will typically include the elapsed or remaining time and the total time in the current file. If the remaining time rather than the elapsed time is shown, it will be preceded with a negative sign or dash (-). To toggle the status bar's visibility, type Alt+I for the View menu, then find the "Status Bar" entry and press Enter to check or uncheck it.
• There are several commands for moving backward and forward through a file, all centering around Left and Right arrows. Use them by themselves or with Alt to move by a few seconds, with Shift for a shorter move, with Ctrl for a longer move than with plain arrows, and with Ctrl+Alt for an even longer jump length.
• To jump to a specific time, type Ctrl+T, type the time in hh:mm:ss format, and press Enter. For those transferring from Winamp, keep in mind that the time must be valid; times like 95:0, legal in Winamp, must be written properly as 1:35:0 in VLC. Entering an invalid time will stop playback and reset the position to the beginning of the file.
• Up and Down arrows, plain or with Ctrl, will raise and lower the output volume.
• With the scripts running, the sequence [ V will report the current volume level as best as can be done. The highest reported level is 125 though, and the volume can be turned up far beyond that point.
• M will mute and unmute the audio output. If it instead opens a menu, press Alt or Esc to exit the menu, then Tab once. After this, M should work as expected.
• For video files with alternative audio tracks, V and Alt+V will cycle forward and backward through the audio tracks available.
• Close VLC with Ctrl+Q.

Using the Advanced Preferences Screen

The Advanced Preferences screen can be reached by typing Ctrl+P from the main screen and using Left and Right arrows to select the All radio button instead of the Simple one. Whereas the Simple view shows a small number of checkboxes that act like a tab control as a means of selecting settings pages, the Advanced view shows a treeView of available pages, along with a search box that can be used to narrow down the pages available.

Typing in the search box will report the number of pages available as you type, so you can detect when your search is producing useful results. When you clear the box with Backspace, JAWS will say "all pages" to indicate that the tree is no longer filtered. Note that these counts represent only what is shown, not what can be reached by opening nodes with the Right arrow in the tree itself. When the tree is not filtered, the tree usually shows mostly just the categories of pages available.

Other Tips and Tricks

• The Comments box in the General tab of Current Media Information (Ctrl+I) does not allow Tab or Shift+Tab to move to another field. To work around this, type Ctrl+Tab once to move to the next tab, then Shift+Tab once to move to the tab control. A Left arrow from there returns to the General tab, from which you can Tab or Shift+Tab through fields.

Known Issues

The following issues are known and may be encountered during use of the application with these JAWS scripts. These issues may be fixed in a future update to the scripts or to the application itself. See also the warning about bugs in VLC itself near the top of this document.

During development of these scripts, this author at first encountered extreme VLC sluggishness during volume adjustment. This cleared up on its own within the first ten minutes of use and never returned.

In some cases, VLC may not display elapsed, remaining, or total times on screen. The scripts will report these anyway whenever possible, even if one of the three values must be calculated from the other two. Such calculations should be rare but have not been tested carefully for files whose total time exceeds 24 hours.

The JAWS command for reading the status line, JAWSKey+PGDN, will announce the status information even if the status bar is not shown on screen, though in the JAWS message voice which is typically slightly lower in pitch than the normal global voice. However, when the status bar is not on screen, there is no way to detect items on the status bar that would be invisible if it were. The usual side effect of this situation is that JAWS will say "DRM" for tracks that are not actually protected by Digital Rights Management technology. Turning the status bar on by typing Alt+I and pressing Enter on the "Status Bar" entry will fix this issue.

Braille support is not well tested and is likely incomplete.

Revision History

This is the revision history of these scripts, most recent revision first:

Revision 48, released May 13, 2024, tested against application version 3.0.20.0

• The standard JAWSKey+PgDn command, for reading the status or bottom line of the current window, reads the status information whether displayed on screen or not. See the Known Issue for reading invisible status bars for a small caveat.
• The command sequences for reading the elapsed, total, and remaining time for the current track, [ T followed by E, T, or R, respectively,
  • Run much faster in some situations.
  • Are no longer confused if the user toggles time display to show remaining time instead of total or elapsed time.
  • Work when a video is showing.
  • Work under several circumstances when no time is visible on screen.

Translators: There are a few changes to one message file.

Revision 36, released April 25, 2024, tested against application version 3.0.20.0

• Initial script release.