Contents

  1. Menu
  2. Prefs
    1. General prefs
      1. Formats
      2. Tools
      3. Other
      4. Saving
    2. Edit players
    3. Edit params
  3. Open URLs
  4. Search in lists
  5. Browsing
    1. Tabs
    2. Search
    3. Video
      1. Playlist
    4. Hotkeys
  6. History and Closed tabs
  7. Bookmarks
  8. Blacklist
  9. Global playlist
  10. Download window
  11. Summary window
  12. Command line URL passing
  13. Troubleshooting
  14. About

Menu

Menu
And next to the menu, the currently set player is displayed. Right to it is the way the program passes the video URLs to the player. Clicking on these will cycle the corresponding options, just like their hotkeys do.

Prefs

General prefs

Prefs are separated to three distinct groups: Formats, Tools and Other.

Formats

Prefs Formats

Formats downloader is the program which can provide the list of the available formats at a video. It supports three template: {URL} which is the placeholder for the YouTube link, {CMD} for the "command" (see right below) and {TARGET} which is the placeholder for the filename where the file will be downloaded.

Format list dl. for formats dl. is one of the "commands" for the Formats downloader's {CMD} template. Up to v1.11.1 there was only this command for the downloader to download the format list, but since v1.12.0 the program supports subtitles too which can be downloaded either internally or with the downloader. For example, for youtube-dl this is '--write-info-json'.

Subtitle dl. flag for formats dl. is the other "commands", which is responsible for telling the downloader to download the subtitles. For example, for youtube-dl this is '--all-subs'.

Obtain formats will decide how the available formats' will be acquired. (Note: since v1.12.0 this also affects the downloading of the subtitles too.) It can be done: If video page load, select format means, that when a video page is opened, then the specified format should be selected in the format selector on the video page. The specified format can be: Ignore formats with these codecs: If the format is selected by either a string or bandwidth, then the selector will ignore any formats which codecs' name contains these strings, separated by a comma character. (Ignored if the formats are obtained from the params list.)

Ignore formats above dimensions of: The program can filter out formats during selection by resolution too. It handles width and height independently, so it can be limited by just one or both. (Also ignored if the formats are obtained from the params list.) The following options are available for both: Filter ignored formats from list: If checked, the dropdown list on the main panel will not list the formats which are ignored during selection.

Tools

Prefs Tools

Player is the selected player from the playerlist which can be edited in Edit players.

Video URLs passed to player: Whenever a video playback is starting, it is done by passing the video's URL to it, however, since v1.5.0, it can be set, which one: Video URLs passed to downloader: Similarly as the other passing option, this is responsible for which URL is passed for downloading, but the options are a bit different: A/V downloader is the program which can download clips from a YouTube URL. The downloader command line acknowledges three templates: {URL}, {TARGET} with identical functions as before and - optionally - {FORMAT} which is the placeholder for the video's format part of the command, with the first part being the format flag (see directly below) and the second part being selected in the format dropdown at the main panel (the video will be downloaded in that format).

Format flag for A/V downloader is the format flag for the set A/V downloader tool. (For example: '-f ' for youtube-dl and yt-dlp. (Note the trailing space!)) Important: the separator char (what separates the flag from the actual header string) must be included! (As shown in the example, this is space for youtube-dl and yt-dlp.)

Do not ask for TARGET by dialog: When copying the download command in the tab menu, normally a file dialog will pop up making it able to choose the download location for the assembled download command. With this option, the dialog can be skipped and the filename which will replace the {TARGET} template will be "TARGET FILENAME".

External pager is the HTTP POST-capable tool which can be used for paging videos and search results. (Not channels!) It supports three templates: {URL} and {TARGET} with identical functions as before and {BODY} which is the placeholder for the HTTP POST query's body. Warning: {BODY} will be replaced with a stream which contains quotes ("), so it should be encapsulated by apostrophes (').

Use external pager will force YTFE to use the external pager for paging videos and search results and the external HTML/IMG downloader (with the headers, see directly below) for paging channels. This is sometimes required, when the internal downloader cannot function properly because of SSL problems or FreePascal's HTTP client crashes under OpenBSD. If every page fails to load, enable this. (But make sure the path is set correctly.)

External HTML/IMG downloader is the program what is capable of downloading content from URL-s. The placeholders and their functions are the same as they are at the A/V downloader, except there is no {FORMAT} here. If not set, by default YTFE will search for curl, fetch, wget, axel, aria2c and ftp in /usr/local/bin/, /usr/sfw/bin/, /usr/bin/, /bin/. In this order.

Header flag for ext. downloader will specify the flag which can be used to specify additional HTTP headers. (For example: '-H ' for curl (Note the trailing space!) or '--header=' for wget.) This is needed for external paging at channels. (Only channels!) Unlike the paging at videos and search results which are paged with HTTP POST queries, the channels are paged via HTTP GET queries, with additional headers, so the program can simply use the external downloader, but needs to be able to specify those headers. Important: the separator char (what separates the flag from the actual header string) must be included! (As shown in the example, this is space for curl and the equal sign for wget.)

Use external HTML/IMG downloader will force YTFE to use the external HTML/IMG downloader, instead of the internal one. This option exists for the very same reasons as the one before: if the internal HTTP client fails, external tools can be used.

Merger: Since v1.12.0 the program is also able to merge the videos which are stored on YouTube as separate video and audio streams, via the program set by this option. (For example: ffmpeg.) It supports the following templates: {AUDIO}, {VIDEO} and {OUTPUT}; these will be replaced at merging with the audio, video and output files' name. (DOH!)

External JavaScript interpreter: On 2022.08.11. Evil Corp has introduced a new version of their "yuck-cipher" in yet another doomed-to-fail attempt to make YouTube latest-Chrome-only and/or make it even harder to watch YouTube without ads. The original internal solution for dealing with this cipher has been rendered useless, so until a new internal solution will be found - and to have a fallback approach if new solutions should also fail at one point - v1.16.0 introduced the option for using an external JavaScript interpreter - such as QuickJS, MuJS, BESEN, GNOME JS or Node.js - for running the cipher and decipher the n signature of YT URL-s which is responsible for dissolving the throttle YouTube is impacting on non-latest-Chrome users. Be advised, that at this point not even the latest snapshot (2022-03-06) of QuickJS seems to be able to deal with the cipher; the problem has been reported to the developers. However, meanwhile it turned out, that the cipher's non-standard date formats were the cause, so since v1.17.0, YTFE can parse and reformat the dates in the cipher, thus QuickJS can interpret them. Node.js (v4.8.2) is tested and working. (Note: Node.js is based on Chrome's V8 engine, so it seems to be a solid fallback option, if the more lightweighted interpreters are unable to run the cipher.) Other JavaScript interpreters are not tested, but some of them may work. The program finds the qjs, mujs, BESENShell, gjs, node and nodejs binaries in the same directories as the other external tools, plus in /usr/lib/nodejs-mozilla/bin/.

Use External JavaScript interpreter: This switches between the external JavaScript interpreter and the internal solution, whatever it may be, an internal JavaScript engine, or a hack... Currently this is forced to be always on, as there are no current internal solution.

Reformat cipher dates to standard: As explained above, QuickJS is currently unable to deal with non-standard-formatted dates, such as "Wednesday December 31 1969 16:01:18 PST". With this option these dates will be parsed and reformatted to be standard-compliant, such as "1969-12-31T16:01:18-08:00", thus QuickJS can handle them. (Other JavaScript interpreters which face the same limitation, will too be usable with this option.) However, as the timezone abbreviations are literally a mess - with several conflicting abbreviations, sometimes multiple times - out of caution and just to be sure, this can be disabled, just to prevent it wrecking the dates undisableabledly for all interpreters if an abbreviation is misinterpreted. Disabling this option and using Node.js as an external JavaScript interpreter should be a safe fallback approach.

Other

Prefs Other

Cache path is the directory where the temporal files will be stored. It needs to be readable and writable.

Cache lifetime sets the lifetime of cached pages in seconds. Any cached page older than this time will no longer be considered valid and it's re-download will be forced.

Empty cache empties the cache. The cache size is displayed beside the button.

Log file is the location of the log file. (DOH II!)

Logging enables or disables logging into the file specified in log file. (DOH III!)

Player logging redirects the player's output from the main program's output to a logging window. See hotkeys for opening the logging window.

Action on close is the operation the frontend will perform when it's main window is closed. It can be the following: Hide when minimized hides the taskbar entry when the program window is minimized,

Tray icons

so it will only shown among the system tray icons. Otherwise,

Taskbar

the taskbar entry will be visible.

Quit hotkey/Tray quit quits without confirm determines if the quit hotkey (Ctrl + Q) and the tray menu's quit option will ask if the program should quit or not. (DOH IV!)

Scroll tab bar to new tab decides if the tab bar should scroll to the newly opened tabs or not.

Prepend user to bookmark titles will put the uploading user's name before the title, when adding a video to the bookmarks. Note: This will not affect bookmarks already in the bookmark list.

Timeout is the amount of time in milliseconds what the program will wait at HTTP queries before stopping the query. Zero means disabled timeout.

Default ordering will be the selected ordering of the searches by default. The search lists can be ordered by relevance, upload date, view count and rating.

Blacklist enabled is self-explanatory.

Persistent connection will preserve and reuse the opened connections to YouTube, even after all the currently needed files (HTML, JSON, XML, images, etc.) for the current video/search page/channel has been downloaded. Theoretically, this should sped up new page loads on VERY old/slow machines (for instance when playing a playlist and switching to a new video), by sparing the time what rebuilding the connection would need.

Show page type on tab will show the same prefixes on the tabs just as it is visible in the different lists; see them at Playlist.

Max. chars on tab will specify how much characters will be displayed on the tab, before it will be truncated. By default, it is 24, the minimum is 16, the maximum is 256.

Check for update at startup will - nomen est omen - make the program check at startup if an updated version is available (by checking this file's content) and throw an information dialog if it is. (Warning: Do not use this under OpenBSD.)

Check now will - also nomen est omen - check instantly if an updated version is available and throw a dialog with the result. (Warning: Do not use this under OpenBSD.)

Saving and resetting

Save saves the current preferences. If everything is OK, then the label beside the buttons will display All OK.
The following errors can happen: Reset will load the default configuration and re-detects the external tools. Note: to keep the restored configuration, the user must click Save manually. (This is a security measure which prevents users accidentally resetting their configurations for good worse.)

Edit players

Edit players

Name is the label what will be displayed in the playerlist in Prefs.

CMD is the command line which will be executed when the play command is given. It knows the {URL}, {AURL}, {FORMAT}, {SUBTITLE} and {TITLE} templates. {URL} works as the same before, except it can accept a direct stream link too, not just a YouTube link. {AURL} is the placeholder of the external audio stream: whenever the player's URL passing is set to direct stream link and a quality is set which is not a single stream, but a separate video and audio stream, this template will be replaced with the External Audio Stream Flag (see directly below) and the direct stream link. {FORMAT} works as it does at the other parts; it's flag is specified at the Format flag (see directly below). {SUBTITLE} will be replaced with the Subtitle flag, plus the external file (see directly below). {TITLE} will be replaced with the Title flag, plus the video's title (see directly below).

Ext. Au. (as in: External Audio Stream Flag) is the flag which will be passed to the player in the {AURL} template.

Format (as in: Format flag) is the flag which will be passed to the player in the {FORMAT} template.

EDL specifies the flag for loading EDL URLs. This is needed, because EDL URLs are much bigger than the few kB-s (MAX_ARG_STRLEN) what a command line can handle. For MPV this flag is --playlist=. However, up to (and including) MPV 0.33.1, MPV cannot load EDL URLs bigger than 512 kB due to an undersized line buffer (see this git commit and this issue) and later versions too, are only able to load EDL files sized up to 2 MB (unless they fixed that since). The workaround is to use this script by copying it into ~/.config/mpv/scripts/ and then specify --idle --script-opts=edl_file= in this field. (Specifying --idle too is important as it will force the program to run despite no input files specified.)

Subt. (as in: Subtitle) specifies the flag for adding an external subtitle for the video. Subtitles are downloaded automatically and passed to the player via this flag. This will be passed to the player in the {SUBTITLE} template.

Title specifies the flag for setting the player's window's caption. Used to set the caption to the video's title. Subtitles are downloaded automatically and passed to the player via this flag. This will be passed to the player in the {TITLE} template.

Insert will add the set parametrs to the list under Name, Update will overwrite the selected entry with them and Delete will remove the selected entry.

Up and Dn will move the selected entry one place up or down in the list.

Edit params

Edit params

This editor is responsible for the additional optional format parameters which can be passed to the player when playing a video. It can be used to select the format of the video to be played.

The editing works exactly the same way as in the players' editor, but Param do not use any templates, it is simply the numeric code of a format. Also, (No params) is a fixed entry, it cannot be edited or removed.

Open URLs

Open URLs

Several URLs can be opened at once, by adding them in this list and clicking Open.
The program accepts several types of YouTube URLs, as shown in the image.

Search in lists

Search in lists

In the Global playlist, the Bookmarks, the Closed tabs, the History and the local playlists, the lists can be searched.
The dropdown offers the macthing method, the textfield contains the searched string; the program can search in the lists for any entry which begins, contains, ends or matches with the searched string.
The two arrow will hunt for the previous or the next match.

Browsing

Tabs

Tabs

Tabs can be moved by drag and drop and closed by the button on their left side.
By clicking on a tab with right button, a menu will pop up with the following choices:

Tab menu
Unlinke browsers, YTFE does not shrinks the tabs until they are completely unreadable and indistinguishable from each other, but shows a window sized portion of them which can be scrolled by the scrollbar under them.

Search

Search

The leftmost textfield directly under the tabs' scrollbar is the search bar. By typing something into it and hitting Return, the program will send the search query to YouTube and display the results.
Next to it, is the current ordering of the results. By default they will be ordered as told in the Prefs. It will reload the page when changed.
Previous page and Next page are the buttons for the previous and next page. Unlike the "old" HTML YouTube, the "new" JS/JSON one only supports Load more content, which means in practice that there is no free paging, it can be paged forward only and only one page at once. But the program caches all fetched pages, so it makes possible to page backward and to select any already fetched page with the textbox between the two buttons. (Hit enter inside, to go to the selected page.)
By clicking on an image with right button, a menu will pop up with the following choices:

Search menu

Video

Video

The images behave the same way as in search. (Left click open, middle click opens in new tab, right click pops up menu.)
The buttons beside the textfield were changed, now they are two groups of them.
The first group belongs to the video, they are always there. Right clicking on the download button will pop up a menu with the following entries:

Download menu The second group belongs to the playlist, if the video is part of a playlist. They only appears then. The upper drop down box at the right edge contains the additional format parameters set in the Param editor. Here it can be selected, which one will be passed to the player or downloader by substitutioning it into the {FORMAT} placeholder. Alternately, if Internally or With formats downloader is selected in Obtain formats in the Prefs, then it will contain the available formats for the current video (but for the latter one, an external tool will be needed to download the formats, like youtube-dl or yt-dlp). Note: If no format selected, at play, the program will automatically play the best available.
The lower drop down box at the right edge contains the subtitles for the video. The program automatically downloads them and if selected, the selected file will be passed to the player via the subtitle flag, set in the Player editor.

Playlist

Playlist

Here any of the elements can be opened by a double click.
Save will save the playlist into a file, for import purposes in the Global playlist.
Save URLs will save only the URLs from the list.
The prefixes are the same in all lists and can be the following: By right clicking on the list, a menu will pop up with the following entries:

Playlist Note: This menu is available in the Global playlist, the Bookmarks, the Closed tabs and the History.

Hotkeys

The following hotkeys can be used:

HotkeyFunction
F1Opens the manual.
Ctrl + BAdds the current tab to the Bookmarks.
Ctrl + DDuplicate tab. Opens the current search or video again on a new tab.
Ctrl + ESwitches between the blacklist being enabled or not.
Ctrl + F8Empties the cache.
Ctrl + IChanges the way the program passes the video URLs to the player.
Ctrl + LOpens the player's log window.
Ctrl + PSwitch to next player.
Ctrl + PgDnSelect next tab.
Ctrl + PgUpSelect previous tab.
Ctrl + QQuit from the program.
Ctrl + RReloads the current tab.
Ctrl + SShows the Summary window.
Ctrl + SpacePlays the currently opened video.
Ctrl + TOpens a new tab.
Ctrl + UGets URLs from the clipboard and opens them as if they were pasted into the URL opener.
Ctrl + WCloses the current tab.
Ctrl + ZOpens the last closed tab again.
Ctrl + PlusMagnify the surface by +10%.
Ctrl + MinusMagnify the surface by -10%.

History and Closed tabs

History

Both History and Closed tabs are simple lists with visited entries, whiches can be double clicked for opening again. Both orders the entries from the last to the first. The last closed tab can be reopened by Ctrl + Z as described in the Hotkeys.
The only two difference between them (aside the triviality that History contains the opened URLs and Closed tabs contains the closed tabs), that History preserves it's content, while Closed tabs does not; it'll be always cleared at exiting. History can be cleared manually with the Clear button.
The other difference is the Save URLs button, which will save the URLs from History into a file.

Bookmarks

Bookmarks

Bookmarks as a list behaves, exactly like Closed tabs or History, the entries can be opened in a new tab by double clicking. Adding entries to it can be done by Ctrl + B or from the tab menu.
Like History, the Bookmarks are preserved too, but unlike History, it cannot be cleared. Entries can be removed by the Delete button. (Multiple selection is available.)
Export saves the current list to a location specified by the save dialog, Import can add an external list to the blacklist, or overwrite it with it. Save URLs will save only the URLs from the list.
Checkboxes can be used to select what type of entries will be shown.

Blacklist

Blacklist

Blacklist hunts for strings in the video's User, Title and Description the very same ways as the list search works. If the hunted string can be found in the way Relation specified in any of the checked fields, then video will not be displayed in the videolist.
Add adds the set data to the list, Store overwrites the selected entry with it and Delete deletes it.
Export and Import works the very same way as at the bookmarks.

Global playlist

Global playlist

Global playlist works exactly the same as the local playlists, exactly this can be edited or loaded.
The editing works as the same way as in the Blacklist, except, here the entries can be moved up and down with the Up and Down buttons. (Multiple selection is available here.) Also while appending and overwriting was both done with Import at Bookmarks and Blacklist, here it is done with Append and Load. Clear and Shuffle clears and shuffles the playlist. (DOH VII!)
Save URLs - as always - will save only the URLs from the list.

Download window

Download window

The download window always contains the actual tab's downloading progress. If an external program used, the stdout and stderr of it will be displayed.

Summary window

Summary window

When the program runs for the first time, it will automatically show this. Elseway, it can be shown by Ctrl + S. It contains some collected information about the settings' validity and some suggestion if problems occurred.

Command line URL passing

The program accepts URL-s passed from command line, even if it is already running: the new instance passes the URL-s to the running one and then exits. There is no any particular template for it, nor any special argument, the URL-s simply can be passed to the binary, separated by space.
If one of the parameters is '-fwm', then either if it is the first instance or a new one, the main window of the program will be shown. If no arguments were given to the second instance, then it will send the '-fwm' parameter to the first.
Alternatively, the main window can be made visible, if the process receives a SIGUSR1 (Linux: 10, FreeBSD/OpenBSD/OSX/macOS: 30, Solaris: 16) signal.

Troubleshooting

Q: I started the program, but no window came up.
A: If a tray is present, then check for the program's icon there and click on it. If there is no tray, then check the tasklist if the program is running. If yes, then it's minimized to the tray (which is not present). Start it again and the new instance will bring up the main window of the first. If the program is not running, then start it from terminal and check the error messages.

Q: A video page came up empty, with only No related videos found. shown and all of the video's properties are blank.
A: YouTube tends to vary it's interface all the time and sometimes the user can run into a server with new data structures which is not yet handled in YTFE. These occurs "randomly", so they are hard to catch. Hit Reload and it will probably be right next time. Or, maybe your blacklist simply hid the videos; check the Description panel and see how much was blacklisted. (Note: The video still can be played when these happens.)

Q: I always get an SSL error when try to search or open a YT link.
A: Use an external downloader and pager, as it explained in the prefs chapter. And please report this, because this should be fixed since FreePascal 3.2.0...

Q: I use OpenBSD and i get a socket error when i try to search, open a YT link or view the next page or download a video by using direct URL passing.
A: The workaround is the same as in the previous answer, but unlike that, this is a known bug not yet fixed in FreePascal, so no need to report it. Just to clarify: no internal HTTP functions are working under OpenBSD: https://forum.lazarus.freepascal.org/index.php/topic,52092.0.html

Q: I use OpenBSD and at exit i get a division by zero error.
A: The program does not divide anything at exiting at all, this is a bug in the FreePascal/Lazarus ecosystem.

Q: I opened a video's page, with URL passing set to direct in the prefs, and after a few hours, if i try to play or download the video from the still opened tab, then it does not work.
A: All direct YT URL-s have an expiration. Reload the page.

Q: Playing or downloading a video is horrendously lagging/slow.
A: YouTube tries to protect it's direct media links with a very disgustingly ciphered signature from being usable by anything but latest Chrome. This cipher is perpetually changing, sometimes into some even more repulsive form, therefore it's interpretation can occasionally break. When facing this throttle (intentional slowdown), YTFE can be switched to use an external JavaScript interpreter. (Carrying Chrome's V8 engine, Node.js should be a safe bet, although there are other - more lightweighted - JavaScript engines.) See the JavaScript options on the tools panel in prefs.


About

YTFE v1.20.5 is written by TCH in 2017-2024.
Changelog is available here.
Report bugs, make requests, curse the programmer by mail at tch@protonmail.com or on our guestbooks at http://oscomp.hu or http://bgafc.t-hosting.hu.