*** Version 1.1.0 Released 8/27/2023 ***:

m3u8 Sniffer TV - "Minimalist" Video Player Documentation

m3u8 Sniffer TV extension Version: 2.0.2
Author: Richard Stam, SigmaFxDx Software
(C) 2021-2024 Richard Stam, All Rights Reserved
Web Site: https://SnifferTV.com/docs

Install this extension from the Chrome Web Store.

Table of Contents:
1 - Introduction to the integrated "Minimalist" Video Player
2 - Player User Interface overview and options documentation
3 - Summary of the integrated video player's keyboard shortcuts
4 - Player Settings Page overview and options documentation
5 - Player Error Handling overview and options documentation
6 - Other interesting player use cases, extensions, and programs
7 - Documentation conclusions and developer contact information


With the extension's integrated m3u8 video stream player, when a m3u8 video stream link is found for a web site you can play it manually with one click or set options to start playing videos automatically when m3u8 links are found on a web site. Once the video is playing you also have options to configure the player as to what to do when streaming errors are encountered or the video playing is stalled. You can handle these manually or set player options to automatically reload the source web site (where the m3u8 link came from) to sniff for m3u8 links again. If you set up the Sniffer to automatically play m3u8 links and the Player to automatically reload the source web sites on playing errors you can have a round-trip setup that will play indefinitely, as long as the source site doesn't fail. Read on for details.

Note: I have been working on a full featured m3u8 / Hls video player for quite a while now, but the deadline to update the extension according to the new Google manifest v3 requirements is fast approaching. I needed to spend most of my time and effort on updating the Sniffer portion of the extension, so I decided to include a "minimalist" player with this release. At least as far as the user interface is concerned it is just an HTML Video element with the standard video control bar. However, I was able to add the features I consider essential for it to be functionally complete, as well as a few extra features. So even though visually it looks like most of the other bare-bones video players out there, the added error handling and Sniffer integration should make it the player of choice for use with the m3u8 Sniffer TV extension. Expect new feature to be added to the player soon. Stay tuned.

The m3u8 Sniffer Integrated Video Player User Interface

This "minimalist" m3u8 video player user interface looks like this:

The CBSN Live News web site with the m3u8 URL link overlay showing at the top.
The CBSN Live News stream played using the m3u8 Sniffer integrated video player.

With this user interface almost all mouse user interactions are done via the standard video control bar with which you can pause / play the stream, control the playback volume, toggle the fullscreen view, and using the options menu (three vertical dots) you can select to show caption texts, control the playback speed, or select the picture in picture mode.

Tip: While the m3u8 overlays won't show while using the integrated video player, you can still access the first and last m3u8 URLs from the Player and Settings pages using the Sniffer extension's popup window.

Other functionalities are provided via the keyboard. The following is a summary of the most useful keys and the descriptions of what they do. In addition to these, if your keyboard (or remote control) has media keys they should also work here.

Warning: These keyboard shortcut assignments might change in future releases of the integrated video player. Check back to this documentation if in doubt.

Keyboard functionalities provided by the video control toolbar:
Space   Toggle the video playing state (Pause / Play).
Up arrow   Increase the video volume (not the computer volume).
Down arrow   Decrease the video volume (not the computer volume).
Left arrow   Decrease the video playing position -n sec (Replay).
Right arrow   Increase the video playing position +n sec (Forward).

Note: It is important to distinguish between the video volume and the system (computer) volume. It should be clear that if you have multiple video players open, the video volume would apply specifically to each player, while modifying (or muting) the system volume would apply to all open players. Also, muting a video's volume will only last until the player page is reloaded (which could happen automatically if you set up automatic reloading), so if you want to leave a player muted and unattended you should mute the system instead of just the video.

Note: Altering the video playing position (Replay) can be unreliable with m3u8 / Hls streams and will depend largely on the behavior of the source site. Some work well but most will only handle short skips back (maybe 30 sec to 5 min). When a playing position seek fails, the video will resume by playing the "live" stream.

Additional keyboard functionalities provided by the player program:
Backspace   Toggle between the Player and Settings pages.
S  key   Open the integrated player's Settings page.
M  key   Toggle the video video volume state (Mute / Unmute).
P  key   Toggle the video playing state (Pause / Play).
Z  key   Toggle the video's fullscreen (Zoom) viewing mode.
[  key   Decrease the video element size (increase margin).
]  key   Increase the video element size (decrease margin).
W  key   Restore the video element size to fill the window.
C  key   Copy the playing m3u8 URL to the system clipboard.
Shift C   Copy the site URL (if available) to the clipboard.
F1  key   Open the video player's documentation web page.
F5  key   Reload the original (source) site if available.
Alt Shift T   Toggle showing the video's tooltip (experimental).

A few of the Chrome browser's keyboard shortcuts that can also be useful:
Alt F  Open the browser's menu, can access bookmarks, history, etc.
Alt Left arrow  Reload the previous browser history page (<).
Alt Right arrow  Reload the next browser history page (>).
Ctrl Shift T  Restore (reopen) the the last closed tab or window page.
For many more see the Chrome keyboard shortcuts documentation page.

Tip: creating a channels library. Since this "minimalist" player doesn't provide a channels (web site) menu, the best way to maintain access to the sites you like to watch would be to use the browser's bookmarks. Also, since the m3u8 stream links from many sites become stale (expire), you are probably better off bookmarking the original (source) site instead of the player with the m3u8 URL. That way you will be starting the player with a fresh m3u8 URL. Also, if you enable the "Handle Direct m3u8 URLs" option you can set up a custom channels list on any web accessible site or document, or anywhere you can access clickable links.

The m3u8 Sniffer Integrated Video Player Settings Page

When a video is playing you can press the "S" key to open the player's settings page:

The m3u8 Sniffer integrated player's setting page.
The m3u8 Sniffer integrated player's setting page.

As you can see it starts by showing the URLs of the site from which the playing m3u8 link was obtained (assuming you got here by pressing the "Play" button from the m3u8 sniffer web page overlay or the extensions popup menu). You can use these links to return to the original (source) web page or the web site's home page. To view the m3u8 links for the video that is playing, use the extension's popup window.

The Integrated Video Player Settings Page Options

The following section describes the options that are available on the settings page:

The On click do drop-down selects what you would like the player to do when you click on the video. Normally most video player's behavior is to toggle Pause / Play. I usually have a video playing while working with many other open windows, so I prefer that clicking on the video's window just sets the focus to that window without pausing. For this I prefer to set this option to "Nothing", and that is the default for this player. You can also set the click action to toggle the video's sound (Mute / Unmute) if you like.

The On double click do drop-down selects what you would like the player to do when you double click on the video. Often the default video player behavior for a double click is to toggle Fullscreen view. That is useful but I prefer to set double click to toggle Mute / Unmute since I do that much more often than toggling fullscreen, and it is easier to double click than to find the volume button on the control bar with the mouse. You can also set the double click to Pause / Play the video or to open the player's Settings Page.

The Integrated Video Player Error Handling Options

The settings options page is also used by the player for error handling. In the case of a video playing error (or stalling), the Setting / Error page will open automatically and show the description of the error. The remaining options on this page will help you handle errors manually or set up options to reload the original (source) web site automatically to try sniffing for fresh m3u8 URLs again.

The following image shows the Setting / Error page displaying a "404 Not Found" error. In this case I know that the error was caused by the m3u8 link being stale (expired) so the problem is easily solved by reloading the site and sniffing it again for a fresh m3u8 link, either manually or automatically. Other common errors for stale (expired) m3u8 links are "400 Bad Request", "403 Forbidden", and "410 Gone", .

The Setting / Error page displaying a '404 Not Found' error.
The Setting / Error page displaying a "404 Not Found" error.

Player options to set up video player streaming error handling:

The Video Stall timeout: Sec drop-down selects how long to wait if the player detects that the video is not playing before considering it as "stalled" and handle it as an error. Most of the time when a m3u8 stream encounters an error the player is notified immediately and the error page will be loaded, but sometimes the video playing just stops and "spins" without throwing any errors. The m3u8 sniffer player can detect when the video is not playing and is "stuck" waiting for the video stream to resume. In these cases we can use this option to specify how long we would accept to wait for the video to resume before considering the video as "stalled" and handling it as an error. The default value is 20 seconds, but you may want to modify this depending on your internet connection speed and computer performance. In particular, if you are using a slower internet connection or computer speed you can increase this value so as to give the stream more time to try to resume. If you set this option to "Off" the player will wait indefinitely for the playing to resume or an error to occur, not recommended if you want the player to be able to automatically reload the site when the video playing stalls.

The Auto Reload wait: Sec drop-down selects how long to wait while showing the error page before reloading the original (source) web site (if available) after an error has occurred. The default value is "Off" which means the player will not try to reload the source page automatically and further actions will need to be handled manually. A recommended value for this option could be 5 seconds, but it could be increased or decreased depending on if you think the source web sites you are using, or your computer, might need more time to "catch up" before trying to sniff for m3u8 links again. If you are experiencing Reload / Play cycles that are looping without success at playing the video, then increasing this value might help.

Note that the Auto Reload option used together with the sniffer's Auto Play option can set up a scenario where you can have the extension sniff a site for a m3u8 link, automatically play the m3u8 if found, and then if a playing error occurs (most often due to the m3u8 link expiring) automatically reload th site to sniff for a new (fresh) m3u8 link. This will allow you to watch the video stream from a site indefinitely, as long as the source web site doesn't fail. If the source web site is failing, then you could end up with an infinite loop of sniffing and error handling, which is why you should set up the reload time so as to not make this loop too frequent and give the source web site some time to see if it can recover.

Finally, this page provides buttons which can be used to handle errors manually:

The   Copy m3u8    button allows you to copy the FIRST m3u8 link found to the clipboard, in the same manner as it does from the m3u8 overlay or the extension's popup window.

The   Reload Site    button is used to manually reload the original (source) web site (if available).

The   Reload Video Player    button is used to manually reload the video player using the same m3u8 link it was playing (or trying to play). In some cases a m3u8 streaming errors could be resolved by simply starting to play it again, or if you got to this page using the "S" (settings) key (no error occurred) you can use this button to resume playing the video again.

Other interesting player use cases:

Multi-video viewing with the Vivaldi browser: At the moment the Vivaldi browser is the only browser I have found which can properly handle viewing multiple tiled video tabs in a single browser window. Although it is somewhat complicated to set up, the following functionalities help make this possible: tab group tiling, tab group stacking, bookmarking tab stacks, setting video sound to "active tab only", restoring the previous session when opening the browser, saving and loading sessions, and proper browser fullscreen viewing. Vivaldi can present some lags with the user interface when many players are running so a bit of patience might be required. That said, once properly set up it works well and looks nice:

Vivaldi browser with 4 tiled video player tabs (in normal view).
Vivaldi browser with 4 tiled video player tabs (in normal view).

Vivaldi browser with 9 tiled video player tabs (in fullscreen).
Vivaldi browser with 9 tiled video player tabs (in fullscreen).

Context menu (right click) channels menu: If you use bookmarks for your favorite sites (channels), preferably in bookmark folders, you can use another chrome extension to make the bookmarks available with a right click (context menu). There are several extension available for this, but the one that has worked best for me is: Context Bookmarks. You will probably want to set the extensions options (filter) to view only the bookmark folder(s) you use for video channel sites. It isn't perfect but it does the job. This is what it looks like:

Player with the Context Menu (right click) shown using the 'Context Bookmarks' extension.
Player with the Context Menu (right click) shown using the "Context Bookmarks" extension.

Using the video player on android devices with the Kiwi browser: As of this writing the only browser that I am aware of that can use Chrome extensions on mobile devices is the Kiwi browser. I have added basic touch capabilities to the player and have gotten it to work nicely on my Android tablet. However, I have only tested it on this one device so you should consider this ability to be purely experimental. If you test it on other mobile devices you can let me know if it is working, or what problems you find, to my m3u8Sniffer email listed below.

The touch functionalities implemented are single and double tap, and to open the Player Settings Page you can use a "three finger tap" or use left and right swipe to toggle between the player and settings pages, or swipe right from the player to return to the source web site (same as the history back button). From there you can configure the player just as you would normally in Chrome. My preference is to set single tap to Mute / Unmute and double tap to Toggle Fullscreen, as well as Auto Reload at 5 sec. It would also be important for best results to go into the extension's popup window and use the "Edit Config Options" to set the "Handle (play) direct m3u8 URLs" to "On". Without this option enabled, Android will load its built in video player instead of the extension's player in some cases. This is what it looks like:

Android tablet with the Kiwi browser and m3u8 Sniffer TV extension installed and playing.
Android tablet with the Kiwi browser and m3u8 Sniffer TV extension installed and playing.

Important: The extension's popup window works differently in the Kiwi browser. Specifically, the popup window opens in a new tab instead of "on top" of the web page as it does in Chrome. In this case when you open (or reload) an extension's popup page it is linked to the tab from which it was opened. You can have multiple popups open, each one tracking the m3u8 links from the web page of the tab to which the popup is linked. If you reload the popup tab, be aware that it will reset its "source" to the tab that has been most recently accessed.

Note: I noticed that trying to play more than one video at a time on my tablet results in the playing being paused on both videos repeatedly. This seems like an Android or Kiwi thing, so if you keep to playing only one video at a time on mobile devices you will get better results.

Conclusion: That's all there is for now regarding the "minimalist" m3u8 Sniffer TV Video Player. Further development in this area should be coming soon. Enjoy!

Contact: If you have any comments or questions you can contact me at:
m3u8Sniffer <-at-> SnifferTV.com.

Your comments and ratings on this extension's chrome store page are appreciated.
Thank you!

The mantra of Reactive Programming


This site will continue to be updated as appropriate.