Using the JAWS Scripts For Youtube
Last Revised October, 2023
This guide provides tips for using these scripts with Youtube and Youtube Music, collectively referred to as
Youtube except where differences must be noted.
When the scripts are installed and Youtube is open and focused in a supported browser, this document can be
opened via a double press of JAWSKey+F1 (or Insert+F1).
Note that Youtube provides many keystrokes that do not require scripts, though they usually do require forms
mode, pass-key-through, or disabling of the virtual cursor. These scripts simplify using some native commands
while providing a few other shortcuts not provided by Youtube itself.
Table of Contents
System Requirements For JAWS Users
These scripts require the following for correct operation with the Youtube web site:
- JAWS 17.0.1806 or greater. (JAWS versions prior to 17.0 do not support web site specific scripts.)
The original JAWS 17.0 release did not include the
GetElementXML() function that was added in the
JAWS 17.0.1806 release in April, 2016.
- A browser supported by JAWS 17.0 or later. At this writing, these are
Internet Explorer, Firefox, Google Chrome,
and Microsoft Edge at least in sufficiently new JAWS versions and since Edge began using Chrome-based technology.
Script Installation Instructions
To install these scripts on a new system:
- Load JAWS if this has not already been done. This will require
administrative privileges on the computer.
- 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.
- 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.
- To verify successful installation, type Insert+Q while
Youtube is in focus in a supported browser. 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.
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.
Using Youtube With JAWS and the Scripts
The scripts provide the following key sequences:
Note that some of the above commands, before executing, will attempt to press the "Hide Cards" button if present
on screen, so that controls required by the script commands become available for action.
If this button is found and pressed, JAWS will say "Hiding cards" before completing the command.
- [ S
- Skip Ad. If a video ad is playing and a Skip button is present and clickable,
this command will click it to make Youtube start playing the actual video requested.
- [ R
- Jump to the top of the right-side column of material on the page, when possible.
This turns out to be a fast way to skip past the scrollable Comments section for a video to reach the rest of
the page, e.g., other videos to play.
- [ Space
- Press the Play/Pause button if present. This works in both virtual cursor mode and forms mode.
- [ T
- Say Time. This command will speak the current time position in the playing video as well as the video's length.
This command also works on Youtube live streams.
If a Youtube Short is playing and it is longer than 30 seconds and shows a progress bar, this command will
announce the percentage complete.
If a video ad is playing, the times will relate to the ad rather than to the requested video.
Note: The current time position is not always kept up to date by Youtube itself but will be
updated if the video is paused and restarted or the play position is changed by the user.
- [ 1 and [ Shift+1
- Speak any currently displayed video caption text,
or cause JAWS to announce such text automatically as it appears until focus leaves the current video window.
See the Reading Caption Text section for further information on these features.
- [ 2
- Speak the current video's subtitle or chapter name if present.
This may, for example, announce the name of the current song or track on a playing album.
Not all videos support this Youtube feature.
This script command is likely to say "not found" when used on a video without this feature.
- [ N and [ Shift+N
- Move to the next or previous page or video. This should work in playlists and
wherever a Next and Previous button can be found.
As of May, 2019, these commands work in Youtube Music to move among songs in the active queue.
Note that the Previous button in a playlist or queue may restart the current video rather than moving to the
previous video unless the video is near the beginning of its playback. Repeat the command to go to the previous
video in this case.
- [ M
- Mute or unmute the current video. See also the M native Youtube command below.
- [ V
- Move focus to the volume slider for the currently playing video. This also switches JAWS into forms mode
and causes a number of native Youtube keystrokes to become usable.
- [ C
- Go to the Youtube channel that owns the current video. This command only works on a video page and does not
work for Youtube Music.
The following Youtube-native keystrokes work as indicated when JAWS is in forms mode or if the keystrokes are
passed through JAWS directly to Youtube, such as with the JAWS "pass next key through" command, Insert+3.
As noted in the below list, some Youtube keystrokes require focus to be on the video's volume slider.
Except where noted, these commands do not apply to Youtube Music pages. Use a question mark
(Shift+/) on those pages to get a list of native keystrokes.
For convenience, the scripts will prevent JAWS from speaking typed characters in forms mode when focus is on a
slider, so that JAWS speech will not disrupt a playing video in response to native Youtube keystrokes.
- Space (slider focus required) or K
- Pause, resume, or play the current video.
Works on Youtube Music pages.
- J or L
- Rewind or fast-forward the video by a few seconds.
- Digits 1 through 9 and 0 (slider focus required)
- Jump to a percentage through the video. 0 jumps to the beginning, 1 to 10% through,
2 to 20% through, etc., and 9 to 90% through.
- Comma (comma) or Period (period)
- Slow down or speed up the video without changing its pitch. This amounts to simple compression or
expansion of the audio and video. Slowing down far enough may stop playback.
- Up or Down arrows (slider focus required)
- Turn up or down the volume of the video by increments of 5%.
Right and Left arrows, respectively, perform the same actions and also require focus to
be on the volume slider.
The volume usually defaults to 100%.
- Mute or unmute the sound of the video. Beware that the occasional video defaults to muted on starting,
though this seems rare.
Works on Youtube Music pages.
- Home (slider focus required)
- Mute the audio. This is not a toggle like M.
- End (slider focus required)
- Unmute the audio and move the volume to 100%. This is not a toggle like M.
- Toggle between full screen and normal video size.
Works on Youtube Music pages.
- / (slash)
- Move focus to the Youtube search box.
Works on Youtube Music pages.
- Apostrophe (apostrophe)
- Pop open and move focus to the Find bar for about four seconds.
Special Script Support For Live Stream Text Chatting
The scripts include a system for handling text chatting during a live stream:
Type the prefix key, the left bracket ([) by default, then type as many of the following keys as
desired to navigate among chat messages. Press Esc to exit the chat review mode when done.
The navigation keys comprise the right-hand portion of the home row on a standard English US QWERTY keyboard:
H goes to and reads the first message, J the previous from current position, L
the next from current position, and the semicolon (;) the last message available.
K repeats the last-read message.
Note that the above features also work in a stream playback after the stream has ended; however, observe the
- When the recording begins playing, the chat area will contain a note indicating that chat messages will appear
at the times they were initially added. This note will be replaced with actual chat messages when they begin to
appear. As a result, the reading position may be invalidated when messages begin to appear in the window.
- As messages appear during playback at the times they were originally added during the live stream, it is
necessary to fast-forward to the end of the stream to gain access to all posted chat messages.
- Rewinding the stream will also remove chats from the display and may invalidate the current reading position.
- If chat reading commands begin producing beep sounds instead of reading messages, reset the reading position
with Alt+Home or Alt+End.
Reading Caption Text
These scripts offer two command sequences for handling closed caption (sometimes also called subtitle) text:
- [ 1 announces any currently displayed caption text.
If no text is found, JAWS will say "no text."
- [ Shift+1 turns on the automatic announcement of caption text as it appears.
Caption text will then be announced continuously until focus next leaves the current video window.
When available, caption text tends to be dialog or indicators of sounds in a video.
Sometimes, such indicators can be informative to blind viewers; for example, "[whirring of lift]" may indicate
that a whirring sound comes from an elevator, which may not be obvious otherwise.
Closed captioning is turned on and off with Shift+C and is more finely controllable from the
Youtube Settings menu.
If neither of these script commands announces any text, make sure the feature is turned on in Youtube itself
for the current video.
The automatic announcement of caption text is currently considered experimental and is subject to various
timing and completeness issues, especially for auto-generated caption and translation text.
To turn off automatic caption announcement, either use Shift+C to toggle the display of captions
off in Youtube itself, or Alt+Tab once out of and back into the video window.
The following issues are known to exist with auto-announcement of caption text:
- Some words or phrases may be missed when the text is auto-generated or auto-translated.
- Occasionally, a word or phrase may speak twice even when it only appears visually once.
Beware, though, that words may legitimately appear multiple times visually as well, such as when the speaker
in the audio track stutters or is interrupted by another person or event.
- Rarely but occasionally, JAWS may speak words or phrases out of order. This appears to occur when Youtube
notifies JAWS of the appearance of text elements in a different order from that in which they visually appear.
This author only observed this phenomenon one time during extensive testing of the auto-announce feature.
The rest of this section consists of notes on what can appear in caption text, the types of caption text that
may be available, and what to expect from JAWS for each.
The following items may appear in caption text, according to this author's experience:
- Plain text indicates the words spoken by performers in the audio.
- Text in square brackets indicates sounds heard in the audio that are not words. Brackets may also be used
to provide speaker names or to indicate that speakers are speaking in a language other than the language of
the presentation as a whole.
[ music ]
[Joe] Heads up!
- The eighth-note character (♪) is sometimes used to indicate music or singing.
Notes on types of captioning:
- Auto-generated caption text appears word by word as a video plays, scrolling continuously. This means
that, at any given moment, the visible text will likely consist of what is currently being spoken and what was
spoken very recently.
Unfortunately, the auto-announcement feature does not always catch all of this moving text; some words may be
- The same is true of auto-translated text, which consists of text in a chosen language that is different
from the language of the video's audio track.
Again, auto-announcement may miss parts of this text at this time.
- When the caption text type is simply named by its language, without "auto-generated" or indication of
translation, it tends to appear in chunks rather than scrolling continuously. It also tends to be more
accurate than auto-generated caption text in some cases, according to this author's experience.
This text speaks far more effectively when auto-announcement is enabled, though from time to time a piece of
text may speak twice.
Issues shown in this section may be fixed in future script
revisions but are not addressed as of this writing.
Sometimes, [ V may announce the volume slider incorrectly. In this script author's
experience, this only occurs after a great number of videos, such as 50, have been played without a browser
Why Youtube Scripts?
As mentioned earlier, Youtube provides many keystrokes natively. However, most are blocked by JAWS' virtual
mode (true for other screen readers as well), making them inconvenient to use in some situations.
I wrote these scripts for at least the following reasons, not necessarily in order of precedence:
- Personal convenience (ok, that one was probably at the top).
- Potential usefulness to other JAWS users.
- A way to make more people aware of the keyboard support built into Youtube itself.
- In the words of a coworker and good friend, why not?
Here is the revision history of these scripts, most recent revision first:
Revision 117, released October 21, 2023
- The [ T sequence for announcing video times will now announce the percentage completion of
Youtube Shorts that show a progress bar.
This happens for Shorts that are over 30 seconds long.
- Some videos were not correctly detected by the code for the [ Shift+1 sequence for setting up
automatic caption announcement. This has been fixed.
Revision 115, released October 2, 2023
- Anyone who downloaded the briefly available script revision 112, before it was replaced with revision 114
on the same day, should download this update to fix a problem that applies to those who use these scripts
but not my Discord scripts.
- The [ C sequence for moving to the channel that owns the current video now works with Youtube
Shorts, moving to the channel to which the currently-playing video belongs.
Revision 114, released September 28, 2023
- The command sequence for moving to the previous video in a playlist is changed from [ P to
[ Shift+N, for consistency with both JAWS itself and other scripts produced by this author.
- The command sequences for pressing Play/Pause ([ Space) and Mute/Unmute ([ M) work
on Youtube Shorts.
Since these tend to start playing automatically as the page scrolls during virtual cursor navigation, this is
especially helpful in recovering the ability to hear JAWS speech.
- Various command sequences that stopped working on Youtube Music pages work there again:
- [ Space for pressing Play/Pause.
- [ M for toggling mute.
- [ V for focusing the volume slider.
- [ N and [ Shift+N for moving to the next and previous track in the queue.
- JAWS will correctly announce the name and status of Like and Dislike buttons on Youtube Music pages.
- [ 1 will speak the caption currently shown for a playing video if one is present,
and [ Shift+1 will initiate automatic announcement of caption text as it appears.
See the Reading Caption Text section for details on these features and on caption text
- [ 2 will
speak the subtitle or chapter name currently shown for a playing video,
if one is present.
This and the previous command sequences use numbers instead of shifted letters like Shift+C and
Shift+S for three reasons:
- To avoid mistakes like opening a video's channel with [ C instead of reading a caption.
- To allow faster checking of a caption.
- To leave room for any further elements that might deserve special access in the future with their own
- By popular vote, old history entries in this document section are now hidden inside a
that may be expanded to show them. Among the benefits of this, heading count is reduced and text searches won't
match very old material.
Revision 96, released January 23, 2023
- The scripts are more effective at finding Play and Pause buttons in some cases.
- The key sequence [ R jumps to the top of the right-side column of material on the page, when possible.
This turns out to be a fast way to skip past the scrollable Comments section for a video to reach the rest of
the page, e.g., other videos to play.
15 older revisions back through July 24, 2016
Revision 93, released July 19, 2022
- Updated the code to find controls on more types of pages.
Improved command key sequences include those for
play/pause ([ Space), mute/unmute ([ M),
volume ([ V), time announcement ([ T),
Next and Previous video ([ N and [ P),
and skip ad ([ S).
- Improved the script installer's ability to detect errors when writing to the JAWS
ConfigNames.ini file that governs when the scripts will be loaded.
Revision 90, released March 18, 2021
- The [ T sequence reads times successfully on live streams where it stopped working because of a
very small change in Youtube HTML code.
- Documentation updated to reflect that the scripts work in Microsoft Edge,
at least in sufficiently new JAWS versions and since Edge began using Chrome-based technology.
Other documentation improvements are also included.
- Fixed a bug that could cause some localized strings not to be spoken where expected.
- Some very old code for supporting JAWS 11 and 12 is removed, and there are a few updates to improve support
for JAWS 2021.
- Added protection against certain kinds of unusual HTML code that could otherwise prevent JAWS scripts from
finding information on a page.
This issue was never seen on Youtube but has been seen in other HTML settings.
- The installer contains version and product information visible from the Details tab in Windows Explorer,
to better identify its contents. This update is being applied to all projects.
- A "directives" text file is included that provides information on how to install this set of scripts manually.
See "Handling Directives Files" in the "Common
Script Elements" document for further information.
Revision 81, released April 26, 2020
- Screen readers respond better to activation of Table of Contents links in this document.
- The messages for these scripts are now distributed in XML rather than jsm files so that translators can
create translations with no need for script source recompilation.
See the Script Translation Procedure document for details on
how to translate these scripts, including how to update the XML message file.
- For those who need to change the Command key, the left bracket ([) by default, the system is
significantly improved, so that you need not type the key or key combination out as a name or string of key
names. You may
edit the keystroke names before accepting them, but JAWS will type them out for you now.
The system is documented in more detail in the Multi-Key
Command Sequence section of my Common Script Elements page.
Revision 74, released June 9, 2019
This revision just updates the scripts' handling of the Skip Ad command sequence, [ S, to work again
after a recent Youtube update in how the Skip Ad button is displayed.
Revision 70, released May 24, 2019
In this revision, I had to replace the live stream chat navigation system with key sequences instead of key
combinations. The primary reason was that the Alt+Left keystroke broke the standard browser keystroke for
pressing the Back button. Alt+Enter also had issues though, and Alt+Right broke the Forward
button command (though I suspect that one is in less common use). Alt with Up and
Down are standard JAWS commands, and similar problems exist for arrows with any other combination of
Alt, Shift, and Ctrl.
See the Special Script Support For Live Stream Text Chatting section of this document for
details on the updated chat navigation system.
Revision 68, released May 18, 2019
- Several features provided by the scripts for Youtube also apply to Youtube Music (music.youtube.com).
This document's "Using Youtube With JAWS and the Scripts" section describes this support as
well as some of the native keystroke support provided directly by Youtube Music.
- Quick navigation of chat messages during a Youtube live stream, or a playback of a past stream, is supported.
See the "Special Script Support For Live Stream Text Chatting" section of this document
Revision 51, released February 24, 2019
- Youtube can display "cards" over the top of a playing video. Since this breaks several scripts, cards will
be hidden as necessary before various commands are executed.
JAWS will say "Hiding cards" when this occurs.
- The [ P command for moving to the previous video in a playlist again works.
- [ T, for reading elapsed and remaining time for a video, also works on live streams.
- Typed characters are silenced while focus is on a slider and forms mode is active, so JAWS will not disrupt
a playing video in response to native Youtube keystrokes.
- Source code to the scripts is no longer included. See my Script
Distribution Policy document for details. As one side effect, this will cause installation to run much faster.
Revision 41, released September 22, 2018
Fixed the method of activating the owning channel page for the [ C command sequence so it works even
if the link is not visible or is only partly displayed.
Revision 40, released September 20, 2018
- Added the [ C command sequence for moving to the channel owning the current video.
The code for this command was contributed by Mohammed Laachir.
- Minor documentation updates.
Revision 36, released August 13, 2018
- Another update to the Skip Ad finding code required by Youtube changes.
- This manual now contains the script revision history.
Revision 35, released July 21, 2018
- The "Skip Ad" command is updated to recognize a revision in the Youtube Skip Ad button.
- [ M mutes or unmutes the current video and works outside of forms mode. The native Youtube
M command requires forms mode or a pass-key-through operation (Insert+3).
- The installer is built with an older Nullsoft installer version, because the newer one previously used had
caused some antivirus software to complain.
- The installer tries drives D and E along with C when looking for JAWS while unable to read the Windows registry.
Revision 30, released September 2, 2017
- Fixed a problem with the previous installer, caused by a change in how the NSIS
command works, that caused the
installer not to find any JAWS versions on 32-bit Windows.
- Failure to find any JAWS versions during installation results in a log display.
Revision 29, released August 31, 2017
- Added JAWS 2018 support.
- Added the ability to edit the Command key by typing the current Command key (the left bracket ([)
followed by JAWSKey+C.
Revision 25, released March 3, 2017
- Important: All script commands, all of which were Ctrl+Shift with another key,
are now the same key but preceded by a left bracket ([) in order to avoid collisions with various
browser-specific native keystrokes.
For example, the command for skipping ads is now [ S instead of Ctrl+Shift+S.
- [+Space (formerly Ctrl+Shift+Space) works on Play buttons when playing a playlist.
(I wrote this one in August and may have forgotten to release it.)
- [+S (formerly Ctrl+Shift+S) should work more often for pressing the "Skip Ad"
button. (Youtube changed some properties of this button and broke the original code.)
- Various user guide updates.
Revision 17, released July 24, 2016
This is the first release of these scripts, including commands for the following:
- Skipping ads.
- Play/pause of a video.
- Announcing time position and length of a playing video.
- Jumping to next and previous videos or search results pages.
- Focusing the volume slider, which enables many native Youtube commands without interferance from JAWS.