**Tartube** is a GUI front-end for `youtube-dl <https://youtube-dl.org/>`__, partly based on `youtube-dl-gui <https://mrs0m30n3.github.io/youtube-dl-gui/>`__ and written in Python 3 / Gtk 3.
- You can download individual videos, and even whole channels and playlists, from YouTube and hundreds of other sites (see `here <https://ytdl-org.github.io/youtube-dl/supportedsites.html>`__ for a full list)
- You can fetch information about those videos, channels and playlists, without actually downloading anything
- If creators upload their videos to more than one website (**YouTube** and **BitChute**, for example), you can download videos from both sites without creating duplicates
- Certain popular websites manipulate search results, repeatedly unsubscribe people from their favourite channels and/or deliberately conceal videos that they don't like. **Tartube** won't do any of those things
-**Tartube** can, in some circumstances, see videos that are region-blocked and/or age-restricted
-`MS Windows (32-bit) installer <https://sourceforge.net/projects/tartube/files/v1.5.007/install-tartube-1.5.007-32bit.exe/download>`__ from Sourceforge
-`MS Windows (64-bit) installer <https://sourceforge.net/projects/tartube/files/v1.5.007/install-tartube-1.5.007-64bit.exe/download>`__ from Sourceforge
-`Source code <https://sourceforge.net/projects/tartube/files/v1.5.007/tartube_v1.5.007.tar.gz/download>`__ from Sourceforge
- It's strongly recommended that you install `Ffmpeg <https://ffmpeg.org/>`__ or `AVConv <https://sourceforge.io/projects/avconv/>`__, too
- Download **Tartube**. Installation is not necessary; you can just run the main script (navigate into the **Tartube** directory, open a terminal window, and type **python3 tartube/tartube**)
MS Windows users should use the installer `available at the **Tartube** website <https://tartube.sourceforge.io/>`__. The installer contains everything you need to run **Tartube**. You must be using Windows Vista or above; the installer will not work on Windows XP.
From v1.4, the installer includes a copy of `AtomicParsley <https://bitbucket.org/jonhedgerows/atomicparsley/wiki/Home>`__, so there is no need to install it yourself.
Some users report that **Tartube** will install but won't run. This problem should be fixed as of v1.2.0 but, if you still have problems, you can try performing a manual installation. This takes about 10-30 minutes, depending on your internet speed.
**Tartube** should run on MacOS, but the authors don't have access a MacOS system. If you are a MacOS user, open an issue at our Github page, and we'll work out the installation procedure together.
-`Python moviepy module <https://pypi.org/project/moviepy/>`__ - if the website doesn't tell **Tartube** about the length of its videos, moviepy can work it out
-`Ffmpeg <https://ffmpeg.org/>`__ or `AVConv <https://sourceforge.io/projects/avconv/>`__ - required for various video post-processing tasks; see the section below if you want to use FFmpeg or AVConv
-`AtomicParsley <https://bitbucket.org/wez/atomicparsley/src/default/>`__ - required for embedding thumbnails in audio files
On other systems, users can modify **Tartube**'s settings. There are several locations on your filesystem where **youtube-dl** might have been installed.
**youtube-dl** can use the `FFmpeg library <https://ffmpeg.org/>`__ or the `AVConv library <https://sourceforge.io/projects/avconv/>`__ for various video-processing tasks, such as converting video files to audio, and for handling large resolutions (1080p and higher). If you want to use FFmpeg or AVConv, you should first install them on your system.
On MS Windows, the usual methods of FFmpeg installation will not work. You **must** download a MinGW-compatible version of FFmpeg. The quickest way to do this is from **Tartube**'s main menu: click **Operations > Install FFmpeg**.
On Linux/BSD, **youtube-dl** might be able to detect FFmpeg/AVConv without any help from you. If not, you can tell **Tartube** where to find FFmpeg/AVConv in this same tab.
On the left side of the **Tartube** window is a list of folders. You can store videos, channels and playlists inside these folders. You can even store folders inside of other folders.
- The **All Videos** folder shows every video in **Tartube**'s database, whether it has been downloaded or not
- The **Bookmarks** folder shows videos you've bookmarked, because they're interesting or important (see `6.16.1 Bookmarked videos`_ )
- The **Favourite Videos** folder shows videos in a channel, playlist or folder that you've marked as a favourite (see `6.16.2 Favourite channels, playlists and folders`_ )
- The **New Videos** folder shows videos that have been downloaded, but not yet watched
- The **Waiting Videos** folder shows videos that you want to watch soon. When you watch the video, it's automatically removed from the folder (but not from **Tartube**'s database)
- Videos saved to the **Temporary Videos** folder will be deleted when **Tartube** next starts
- The **Unsorted Videos** folder is a useful place to put videos that don't belong to a particular channel or playlist
Copy and paste the channel's URL into the dialogue window. You should also give the channel a name. The channel's name is usually the name used on the website (but you can choose any name you like).
When adding a long list of URLs, containing a mixture of channels, playlists and individual videos, it's quicker to add them all at the same time. Click the **'Videos'** button near the top of the window, and paste all the links into the dialogue window.
**Tartube** doesn't know anything about these links until you actually download them (or check them). If it's expecting an individual video, but receives a channel or a playlist, **Tartube** will the handle the conversion for you.
By default, **Tartube** converts a link into a channel, when necessary. You can change this behaviour, if you want to.
- After converting, you can set a name for the new channel/playlist by right-clicking it, and selecting **Channel actions > Rename channel...** or **Playlist actions > Rename playlist...**
The left-hand side of the window will quickly still filling up. It's a good idea to create some folders, and to store your channels/playlists inside those folders.
Once you've finished adding videos, channels, playlists and folders, you can make **Tartube** do something. **Tartube** offers the following operations:
-**Check** - Fetches information about videos, but don't download them
-**Download** - Actually downloads the videos. If you have disabled downloads for a particular item, **Tartube** will just fetch information about it instead
-**Custom download** - Downloads videos in a non-standard way; see `6.13 Custom downloads`_
-**Refresh** - Examines your filesystem. If you have manually copied any videos into **Tartube**'s data directory, those videos are added to **Tartube**'s database
-**Update** - Installs or updates **youtube-dl**, as described in `6.2 Check youtube-dl is updated`_. Also installs FFmpeg (on MS Windows only); see `6.4 Setting the location of FFmpeg / AVConv`_
-**Info** - Fetches information about a particular video: either the available video/audio formats, or the available subtitles
-**Tidy** - Tidies up **Tartube**'s data directory, as well as checking that downloaded videos still exist and are not corrupted
To **Check** or **Download** videos, channels and playlists, use the main menu, or the buttons near the top of the window, or right-click an individual video, channel or playlist. A **Custom Download** can be started from the main menu or by right-clicking.
To **Refresh****Tartube**'s database, use the main menu (or right-click a channel/playlist/folder).
Those are the *default* download options. If you want to apply a *different* set of download options to a particular channel or particular playlist, you can do so.
In the new window, click the **'OK'** button. The options are applied to *everything* in the **Music folder**. A pen icon appears above the folder to remind you of this.
By default, **Tartube** downloads videos as quickly as possible using each video's original address (URL).
A **Custom download** enables you to modify this behaviour, if desired. It's important to note that a custom download behaves exactly like a regular download until you specify the new behaviour.
- Click **Edit > System preferences... > Operations > Custom**
- Select one or more of the three options to enable them
- To start the custom download, click **Operations > Custom download all**
6.13.1 Independent downloads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, **Tartube** instructs the underlying **youtube-dl** software to download from a channel or a playlist; it doesn't actually supply a list of videos in each channel/playlist. **youtube-dl** is perfectly capable of working out that information for itself.
If you need to download videos directly, for any reason, you can:
- Firstly, fetch the list of videos, for example by clicking **Operations > Check all**
- Click **Edit > System preferences... > Operations > Custom**
- Click **In custom downloads, download each video independently of its channel or playlist** to select it
- You can now start the custom download
6.13.2 Diverting to HookTube/Invidious
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If **Tartube** can't download a video from YouTube, it's sometimes possible to obtain it from an alternative website instead.
- Click **Edit > System preferences... > Operations > Custom**
- Click **In custom downloads, obtain the video from HookTube rather than YouTube** to select it
- Alternatively click **In custom downloads, obtain the video from Invidious rather than YouTube** to select it
- You can now start the custom download
HookTube/Invidious can only handle requests for videos, not whole channels or playlists. You should normally enable independent downloads as well.
6.13.3 Delays between downloads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If a video website is complaining that you are downloading videos too quickly, it's possible to add a delay betwen downloads. The delay can be of a fixed or random duration.
The delay is applied after downloading a channel or a playlist. If you want to apply the delay after each video, you should enable independent downloads as well.
If it's a YouTube video that is restricted (not available in certain regions, or without confirming your age), it's sometimes possible to watch the same video without restrictions on the **HookTube** and/or **Invidious** websites.
6.15 Filtering and finding videos
---------------------------------
Beneath the videos you'll find a toolbar. The buttons are self-explanatory, except for the one on the right.
..image:: screenshots/example18.png
:alt:The video catalogue toolbar
Click that button, and a second row of buttons is revealed. You can use these buttons to filter out videos, change the order in which videos are displayed, or find a video uploaded at a certain date.
..image:: screenshots/example19.png
:alt:The toolbar's hidden buttons revealed
- Click the **Sort by** button to sort the videos alphabetically
- Click the button again to sort the videos by date of upload
- Click the **Find date** button to select a date. If there are more videos than will fit on a single page, **Tartube** will show the page containing the videos uploaded closest to this date
You can search for videos by applying a filter. For example, you could search for videos whose name contains the word **PewDiePie**:
- In the **Filter** box, type **pewdiepie**
- The search is case-insensitive, so it doesn't matter if you type **PewDiePie** or **pewdiepie**
- Click the magnifiying glass button. All matching videos are displayed
- Click the cancel button next it to remove the filter
You can search using a *regular expression* (regex), too. These searches are also case-insensitive. For example, to find all videos whose name begins with the word "village":
- In the **Filter** box, type **\^village**
- Click the **Regex** button to select it
- Click the magnifying glass button. All matching videos are displayed
- To search using ordinary text, rather than a regex, de-select the **Regex** button
6.16 Marking videos
-------------------
You can mark videos, channels, playlists and folders that you find interesting, or which are important.
- You can **favourite** a channel, playlist or folder
Bookmarked and favourite videos shouldn't be confused with archived videos, which are protected from automatic deletion - see `6.18 Archiving videos`_.
6.16.1 Bookmarked videos
~~~~~~~~~~~~~~~~~~~~~~~~
There are several ways to bookmark a video.
- Right-click a video, and click **Video is bookmarked** to select it
- If the **Bookmarked** label is visible under the video's name, click it
- Right-click a channel, and select **Channel contents > Mark as bookmarked**. This will bookmark every video in the channel, but it won't bookmark videos that are added to the channel later
- (This can also be done with playlists and folders)
A bookmarked video appears in **Tartube**'s own **Bookmarks** folder, as well as in its usual location.
6.16.2 Favourite channels, playlists and folders
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you mark a channel, playlist or folder as a favourite, all of its videos will also be visible in **Tartube**'s own **Favourite Videos** folder.
If new videos are later added to the channel, playlist or folder, they will automatically appear in the **Favourite Videos** folder.
(It's possible to mark or unmark an individual video as a favourite, but it's better to use bookmarking for that.)
- Right-click a channel, and select **Channel contents > Mark as favourite**
- Right-click a playlist, and select **Playlist contents > Mark as favourite**
- Right-click a folder, and select **Folder contents > All contents > Mark as favourite**
- If you just want to mark a folder's videos as favourite, and not any channels or playlists it contains, select **Folder contents > Just folder videos > Mark as favourite**
**Tartube** can download videos from several channels and/or playlists into a single directory (folder) on your computer's hard drive. There are three situations in which this might be useful:
- A channel has several playlists. You have added both the channel and its playlists to **Tartube**'s database, but you don't want to download duplicate videos
- A creator releases their videos on **BitChute** as well as on **YouTube**. You have added both channels, but you don't want to download duplicate videos
- You don't care about keeping videos in separate directories/folders on your filesystem. You just want to download all videos to one place
A creator might have a single channel, and several playlists. The playlists contain videos from that channel (but not necessarily *every* video).
You can add the channel and its playlists in the normal way but, if you do, **Tartube** will download many videos twice.
The solution is to tell **Tartube** to store all the videos from the channel and its playlists in a single location. In that way, you can still see a list of videos in each playlist, but duplicate videos are not actually downloaded to your filesystem.
- Click **Media > Add channel**..., and then enter the channel's details
- Click **Media > Add playlist**... for each playlist
- Now, right-click on each playlist in turn and select **Playlist actions > Set download destination...**
- In the dialogue window, click **Choose a different directory/folder**, select the name of the channel, then click the **OK button**
A creator might release their videos on **YouTube**, but also on a site like **BitChute**. Sometimes they will only release a particular video on **BitChute**.
You can add both channels in the normal way but, if you do, **Tartube** will download many videos twice.
The solution is to tell **Tartube** to store videos from both channels in a single location. In that way, you can still see a list of videos in each channel, but duplicate videos are not actually downloaded to your filesystem.
- Click **Media > Add channel**..., and then enter the **YouTube** channel's details
- Click **Media > Add channel**..., and then enter the **BitChute** channel's details
- Right-click the **BitChute** channel and select **Channel actions > Set download destination...**
- In the dialogue window, click **Choose a different directory/folder**, select the name of the **YouTube** channel, then click the **OK button**
It doesn't matter which of the two channels you use as the download destination. There is also no limit to the number of parallel channels, so if a creator uploads videos to a dozen different websites, you can add them all.
If you don't care about keeping videos in separate directories/folders on your filesystem, you can download *all* videos into the **Unsorted videos** folder. Regardless of whether you have added one channel or a thousand, all the videos will be stored in that one place.
- Click the **Download all videos into this folder** button to select it
- In the combo next to it, select **Unsorted Videos**
Alternatively, you could select **Temporary Videos**. If you do, videos will be deleted when you shut down **Tartube** (and will not be re-downloaded in the future).
- Click the **Automatically delete downloaded videos after this many days** button to select it
- If you want to, change the number of days from 30 to some other value
If you want to protect your favourite videos from being deleted automatically, you can *archive* them. Only videos that have actually been downloaded can be archived.
- Right-click a video, and select **Video is archived**
You can also archive all the videos in a channel, playlist or folder.
- For example, right-click a folder and select **Channel contents > Mark videos as archived**
- This action applies to *all* videos that are *currently* in the folder, including the contents of any channels and playlists in that folder
- It doesn't apply to any videos you might download in the future
**Tartube** downloads all of its videos into a single directory (folder) - the **Tartube data directory**. The contents of this directory comprise the **Tartube database**.
*You should not use this directory (folder) for any other purpose*.
**Tartube** stores important files here, some of which are invisible (by default). Don't let other applications store their files here, too.
*You can modify the contents of the directory yourself, if you want, but don't do it while **Tartube** is running.*
It's fine to add new videos to the database, or to remove them. Just be careful that you don't delete any sub-directories (folders), including those which are hidden, and don't modify the **Tartube** database file, **tartube.db**.
6.19.1 Importing videos from other applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Tartube** is a GUI front-end for `youtube-dl <https://youtube-dl.org/>`__, but it is not the only one. If you've downloaded videos using another application, this is how to add them to **Tartube**'s database.
- In **Tartube**'s main window, add each channel and playlist in the normal way
- When you're ready, click the **Check all** button. This adds a list of videos to **Tartube**'s database, without actually downloading the videos themselves
- Copy the video files into **Tartube**'s data directory (folder). For example, copy all your **PewDiePie** videos into **../tartube-data/downloads/PewDiePie**
- In the **Tartube** menu, click **Operations > Refresh database**. **Tartube** will search for video files, and try to match them with the contents of its database
- The whole process might some time, so be patient
6.19.2 Multiple databases
~~~~~~~~~~~~~~~~~~~~~~~~~
**Tartube** can only use one database at a time, but you can create as many as you want.
For example, if you've just bought an external hard drive, you can create a new database on that hard drive.
- In the main menu, click **File > Database preferences...**
- In the new window, click the **Change** button
- Another new window appears. Use it to create a directory (folder) on your external hard drive
**Tartube** remembers the location of the databases it has loaded. To switch back to your original database:
- In the main menu, click **File > Database preferences...**
- In the list, click the path to the original database to select it
- Click the **Switch** button
6.19.3 Multiple Tartubes
~~~~~~~~~~~~~~~~~~~~~~~~
**Tartube** can't load more than one database, but you can run as many instances of **Tartube** as you want.
If you have added three databases to the list, and if you have three **Tartube** windows open at the same time, then by default each window will be using a different database.
By default, the databases are loaded in the order they appear in the list.
You can export the contents of **Tartube**'s database and, at any time in the future, import that information into a different **Tartube** database, perhaps on a different computer.
It is important to note that *only a list of videos, channels, playlists, folders are exported*. The videos themselves are not exported, and neither are any thumbnail, description or metadata files.
- Click **Media > Export from database**
- In the dialogue window, choose what you want to export
- If you want a list of videos, channels and playlists that you can edit by hand, select the **Export as plain text** option
- Click the **OK** button, then select where to save the export file
It is safe to share this export file with other people. It doesn't contain any personal information.
This is how to import the data into a different **Tartube** database.
A: Please report any problems to the authors at our `Github page <https://github.com/axcore/tartube/issues>`__
A: Crashes are usually caused by the Gtk graphics library. Depending on the version of the library installed on your system, **Tartube** may restrict some minor cosmetic features, or not, in an effort to avoid such crashes.
If crashes are a problem, you can force **Tartube** to restrict those cosmetic features, regardless of your current Gtk library.
- Click **Edit > System preferences... > General > Modules**
- Click **Assume that Gtk is broken, and disable some minor features** to select it
A: Make sure **youtube-dl** is updated; see `6.2 Check youtube-dl is updated`_
A: Before submitting a `bug report <https://github.com/axcore/tartube/issues>`__, find out whether **Tartube** is responsible for the problem, or not. You can do this by opening a terminal window, and typing something like this:
**youtube-dl <url>**
...where **\<url\>** is the address of the video. If the video downloads successfully, then it's a **Tartube** problem that you can report. If it doesn't download, you should submit a bug report to the authors of `youtube-dl <https://github.com/ytdl-org/youtube-dl/issues>`__ instead.
Because most people don't like typing, **Tartube** offers a shortcut.
- Click **Operations > Test youtube-dl**, or right-click a video, and select **Downloads > Test system command**
- In the dialogue window, enter the address (URL) of the video
- You can add more **youtube-dl** download options, if you want. See `here <https://github.com/ytdl-org/youtube-dl/>`__ for a complete list of them
- Click the **OK** button to close the window and begin the test
- Click the **Output** Tab to watch the test as it progresses
- When the test is finished, a temporary directory (folder) opens, containing anything that **youtube-dl** was able to download
A: **Tartube** creates a backup copy of its database, before trying to save a new copy. In the unlikely event of a failure, you can replace the broken database file with the backup file.
- Open the data directory (folder). If you're not sure where to find **Tartube**'s data directory , you can click **Edit > System preferences... > Filesystem > Database**
- Make sure **Tartube** is not running. The **Tartube** window is sometimes minimised, and sometimes only visible in the system tray. A good way to make sure is to run **Tartube**, then close it by clicking **File > Quit**
**Tartube** can make more frequent backups of your database file, if you want. See the options in **Edit > System preferences... > Filesystem > Backups**.
You can drastically reduce the time this takes by telling **Tartube** to stop checking/downloading videos, if it receives (for example) notifications for three videos it has already checked/downloaded.
This works well on sites like YouTube, which send information about videos in the order they were uploaded, newest first. We can't guarantee it will work on every site.
**Q: I clicked the 'Download all' button, but the operation takes so long! It only downloaded two new videos!**
A: **youtube-dl** can create an archive file especially for the purpose of speeding up downloads, when some of your channels and playlists have no new videos to download, but when others do.
To enable this functionality, click **Edit > System preferences... > youtube-dl > Allow youtube-dl to create its own archive**. The functionality is enabled by default.
**Q: Tartube always downloads its channels and playlists into ../tartube-data/downloads. Why doesn't it just download directly into ../tartube-data?**
A: This was implemented in v1.4.0. If you installed an earlier version of **Tartube**, you don't need to take any action; **Tartube** can cope with both the old and new file structures.
If you installed an earlier version of **Tartube**, and if you want to move your channels and playlists out of **../tartube-data/downloads**, this is how to do it:
- Open the data directory (folder). If you're not sure where to find **Tartube**'s data directory, you can click **Edit > System preferences... > Filesystem > Database**.
- Make sure **Tartube** is not running. The **Tartube** window is sometimes minimised, and sometimes only visible in the system tray. A good way to make sure is to run **Tartube**, then close it by clicking **File > Quit**
- Now open the **downloads** directory
- Move everything inside that directory into the directory above, e.g. move everything from **../tartube-data/downloads** into **../tartube-data**
- Delete the empty **downloads** directory
- You can now restart **Tartube**
**Q: I want to convert the video files to audio files!**
**Q: The main window is full of folders I never use! I can't see my own channels, playlists and folders!**
A: Right-click the folders you don't want to see, and select **Folder actions > Hide folder**. To reverse this step, in the main menu click **Media > Show hidden folders**
A: In the main menu, click **Edit > System preferences... > Windows > Main window > Show smaller icons in the Video Index** to select it
A: If you have many channels and playlists, create a folder, and then drag-and-drop the channels/playlists into it
**Tartube** is a Linux application. The installer for MS Windows contains not just **Tartube** itself, but a copy of Python and a whole bunch of essential graphics libraries, all of them ported to MS Windows.
If you're at all suspicious that such a small application uses such a large installer, you are invited to examine the installed files for yourself:
**C:\\Users\\YOURNAME\\AppData\\Local\\Tartube**
(You might need to enable hidden folders; this can be done from the Control Panel.)
Everything is copied into this single folder. The installer doesn't modify the Windows registry, nor does it copy files anywhere else (other than to the desktop and the Start Menu).
The NSIS scripts used to create the installers can be found here: