- 1 Introduction
- 2 Why should I use Tartube?
- 3 Downloads
- 4 Quick start guide
- 5 Installation
- 6 Using Tartube
- 7 Frequently-Asked Questions
- 8 Contributing
- 9 Authors
- 10 License
Tartube is a GUI front-end for youtube-dl, partly based on youtube-dl-gui and written in Python 3 / Gtk 3.
It runs on MS Windows, Linux and BSD. It probably works on MacOS, but the authors have not been able to confirm this.
Problems can be reported at our GitHub page.
- You can download individual videos, and even whole channels and playlists, from YouTube and hundreds of other websites (see here for a full list)
- You can fetch information about those videos, channels and playlists, without actually downloading anything
- Tartube will organise your videos into convenient folders (if that's what you want)
- Tartube can alert you when livestreams are starting (YouTube only)
- 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
- Tartube is free and open-source software
- For everyone who wants a simpler way to download videos, a new Classic Mode, emulating the look and feel of youtube-dl-gui - see 6.21 Classic Mode
- Tartube can now detect livestreams, and alert you when they start - see 6.22 Livestreams. This feature is EXPERIMENTAL, has only been tested on YouTube, and may not be reliable.
- If you can contribute a translation to this project, please read this. As a proof of concept, Tartube can now be used with either British or American English
Latest version: v2.1.0 (7 May 2020)
- MS Windows (32-bit) installer from Sourceforge
- MS Windows (64-bit) installer from Sourceforge
- DEB package (for Debian-based distros, e.g. Ubuntu, Linux Mint) from Sourceforge
- RPM package (for RHEL-based distros, e.g. Fedora) from Sourceforge
- Gentoo ebuild (available in src_prepare-overlay) from Gitlab
- Source code from Sourceforge
- Source code and support from GitHub
There are also DEB/RPM packages marked STRICT. In these packages, updates to youtube-dl from within Tartube have been disabled. If Tartube is uploaded to a repository with lots of rules, such as the official Debian repository, then you should probably use the STRICT packages.
- Download, install and run Tartube, using the links above
- When prompted, choose a folder where Tartube can store videos
- When prompted, let Tartube install youtube-dl for you
- It's strongly recommended that you install FFmpeg. From the menu, click Operations > Install FFmpeg
If you don't want Tartube to add videos to its database, click the Classic Mode Tab. If you do want to update the database, do this instead:
- Go to the YouTube website, and find your favourite channel
- In Tartube, click the Add a new channel button (or from the menu, click Media > Add channel... )
- In the dialogue window, add the name of the channel and the address (URL)
- Click the OK button to close the window
- Click the Check all button. Tartube will fetch a list of videos in the channel
- Click All Videos to see that list
- If you want to download the videos, click the Download all button
- Install Tartube by downloading the DEB or RPM package from the links above. Alternatively, install it from PyPI, using the instructions below
- It's strongly recommended that you install Ffmpeg or AVConv, too
- Run Tartube
- When prompted, choose a directory where Tartube can store videos
- Install youtube-dl by clicking Operations > Update youtube-dl
If you don't want Tartube to add videos to its database, click the Classic Mode Tab. If you do want to update the database, do this instead:
- Go to the YouTube website, and find your favourite channel
- In Tartube, click the Add a new channel button (or from the menu, click Media > Add channel... )
- In the dialogue window, add the name of the channel and the address (URL)
- Click the OK button to close the window
- Click the Check all button. Tartube will fetch a list of videos in the channel
- Click All Videos to see that list
- If you want to download the videos, click the Download all button
MS Windows users should use the installer available at the Tartube website. 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.
If you want to use FFmpeg, see 6.4 Setting the location of FFmpeg / AVConv.
From v1.4, the installer includes a copy of AtomicParsley, 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 but, if you still have problems, you can try performing a manual installation. This takes about 10-30 minutes, depending on your internet speed.
This section assumes you have a 64-bit computer
Download and install MSYS2 from msys2.org. You need the file that looks something like msys2-x86_64-yyyymmdd.exe
MSYS2 wants to install in C:\msys64, so do that
Open the MINGW64 terminal, which is C:\msys64\mingw64.exe
In the MINGW64 terminal, type:
pacman -Syu
If the terminal wants to shut down, close it, and then restart it
Now type the following commands, one by one:
pacman -Su
pacman -S mingw-w64-x86_64-python3
pacman -S mingw-w64-x86_64-python3-pip
pacman -S mingw-w64-x86_64-python3-gobject
pacman -S mingw-w64-x86_64-python3-requests
pacman -S mingw-w64-x86_64-gtk3
pacman -S mingw-w64-x86_64-gsettings-desktop-schemas
pip3 install feedparser
pip3 install playsound
Download the Tartube source code from Sourceforge, using the links above
Extract it into the folder C:\msys64\home\YOURNAME, creating a folder called C:\msys64\home\YOURNAME\tartube
Now, to run Tartube, type these commands in the MINGW64 terminal (don't forget to use forward slashes):
cd /home/YOURNAME/tartube
python3 tartube/tartube
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.
Linux/BSD users can use any of the following installation methods.
Linux distributions based on Debian, such as Ubuntu and Linux Mint, can install Tartube using the DEB package (see the links above). Linux distributions based on RHEL, such as Fedora, can install Tartube using the RPM package (see the links above). Gentoo users can install Tartube using the ebuild (see the link above).
Tartube requires youtube-dl. If it's already installed on your system, then you can start Tartube immediately.
Otherwise, if pip is already installed on your system, do this:
- Run Tartube
- Tartube asks you to choose a data directory, so do that
- Click Operations > Update youtube-dl
If neither youtube-dl nor pip are installed on your system, then the recommended way to install youtube-dl is from the command line, using pip. (Software managers usually don't offer the most recent version of youtube-dl.)
This is the procedure on Debian-based distributions, like Ubuntu and Linux Mint. The procedure on other distributions is probably very similar.
- Open a terminal window
- Type:
sudo apt install python3-pip - Type:
pip3 install youtube-dl - You can now run Tartube.
Tartube can be installed from PyPI with or without root privileges.
Here is the procedure for Debian-based distributions, like Ubuntu and Linux Mint. The procedure on other distributions is probably very similar.
- Make sure youtube-dl has been completely removed from your system
- Type:
sudo apt install python3-pip - Type:
sudo pip3 install youtube-dl tartube - Type:
tartube
- Type:
sudo apt install python3-pip - Type:
pip3 install tartube - The Tartube executable is stored in ~/.local/bin by default. If that is already in your path, you can start Tartube by typing
tartube. Otherwise, type~/.local/bin/tartube - Tartube asks you to choose a data directory, so do that
- In the Tartube main window, click Edit > System preferences... > youtube-dl
- In the box marked Actual path to use, select Use PyPI path (~/.local/bin/youtube-dl)
- Click OK to close the dialogue window
- Click Operations > Update youtube-dl
- Once the update has finished, Tartube is ready for use
For any other method of installation, the following dependencies are required:
These dependencies are optional, but recommended:
- Python pip - keeping youtube-dl up to date is much simpler when pip is installed
- Python feedparser module - enables Tartube to detect livestreams
- Python moviepy module - if the website doesn't tell Tartube about the length of its videos, moviepy can work it out
- Python playsound module - enables Tartube to play an alarm when a livestream starts
- Ffmpeg or AVConv - required for various video post-processing tasks; see the section below if you want to use FFmpeg or AVConv
- AtomicParsley - required for embedding thumbnails in audio files
After installing dependencies (see above):
- Download & extract the source code (see the links above)
- Change directory into the Tartube directory
- Type:
python3 setup.py install - Type:
tartube
After installing dependencies (see above):
- Download & extract the source code (see the links above)
- Change directory into the Tartube directory
- Type:
python3 tartube/tartube
- 6.1 Choose where to save videos
- 6.2 Check youtube-dl is updated
- 6.3 Setting youtube-dl's location
- 6.4 Setting the location of FFmpeg / AVConv
- 6.4.1 On MS Windows
- 6.4.2 On Linux/BSD
- 6.5 Introducing system folders
- 6.6 Adding videos
- 6.7 Adding channels and playlists
- 6.8 Adding videos, channels and playlists together
- 6.9 Adding folders
- 6.10 Things you can do
- 6.11 General download options
- 6.12 Other download options
- 6.13 Custom downloads
- 6.13.1 Independent downloads
- 6.13.2 Diverting to HookTube / Invidious
- 6.13.3 Delays between downloads
- 6.14 Watching videos
- 6.15 Filtering and finding videos
- 6.16 Marking videos
- 6.16.1 Bookmarked videos
- 6.16.2 Favourite channels, playlists and folders
- 6.17 Combining channels, playlists and folders
- 6.17.1 Combining one channel and many playlists
- 6.17.2 Combining channels from different websites
- 6.17.3 Download all videos to a single folder
- 6.18 Archiving videos
- 6.19 Managing databases
- 6.19.1 Importing videos from other applications
- 6.19.2 Multiple databases
- 6.19.3 Multiple Tartubes
- 6.19.4 Exporting/importing the database
- 6.20 Converting to audio
- 6.21 Classic Mode
- 6.22 Livestreams
- 6.22.1 Detecting livestreams
- 6.22.2 Customising livestreams
- 6.22.3 Livestream notifications
- 6.22.4 Compatible websites
When you first start Tartube, you will be asked to choose where Tartube should save its videos.
Regardless of which location you select, you can change it later, if you need to - see 6.19 Managing databases
- In the main menu, click File > Database preferences...
- In the new window, check the location of the Tartube data directory
- If you want to change it, click the Change button
If you installed Tartube via a repository such as the official Debian repository, then Tartube may not be allowed to update youtube-dl, in which case this section does not apply.
Tartube uses youtube-dl to interact with websites like YouTube. You should check that youtube-dl is also installed and running correctly.
If you are using MS Windows, you will be prompted to install youtube-dl; you should click Yes.
youtube-dl is updated every week or so. You can check that youtube-dl is installed and up to date:
- Click Operations > Update youtube-dl
If the update operation fails on MS Windows, you should ask the authors for help.
On other systems, users can modify Tartube's settings. There are several locations on your filesystem where youtube-dl might have been installed.
- Click Edit > System preferences... > youtube-dl
- Try changing the setting Actual path to use
- Try changing the setting Shell command for update operations
- Try the update operation again
youtube-dl can use the FFmpeg library or the AVConv library 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 an Msys2-compatible version of FFmpeg. The quickest way to do this is from Tartube's main menu: click Operations > Install FFmpeg.
There is no known method of installing a compatible version of AVConv.
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.
Tartube saves videos on your filesystem using exactly the same structure.
When you start Tartube, there are seven folders already visible. You can't remove any of these folders (but you can hide them, if you want).
- 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 Livestreams folder shows livestreams. Videos are automatically removed from this folder (but not from other folders) when the livestream is finished
- 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
If you want a simpler way to download videos, see 6.21 Classic Mode.
You can add individual videos by clicking the 'Videos' button near the top of the window. A dialogue window will appear.
Copy and paste the video's URL into the dialogue window. You can copy and paste as many URLs as you like.
When you're finished, click the OK button.
Finally, click on the Unsorted Videos folder to see the videos you've added.
You can also add a whole channel by clicking the 'Channel' button or a whole playlist by clicking the 'Playlist' button.
Tartube will download all of the videos in the 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.
- In Tartube's main window, click Edit > System preferences... > Operations > URL flexibility
- Select one of the behaviours listed there
Unfortunately, there is no way for Tartube to distinguish a channel from a playlist. Most video websites don't supply that information.
If your list of URLs contains a mixture of channels and playlists, you can convert one to the other after the download has finished.
- In Tartube's main window, right-click a channel, and select Channel actions > Convert to playlist
- Alternatively, right-click a playlist, and select Channel actions > Convert to channel
- 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.
Click the 'Folder' button near the top of the window, and create a folder called Comedy.
Then repeat that process to create a folder called Music. You can then drag-and-drop your channels and playlists into 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).
Protip: Do an 'Update' operation before you do a 'Check' or 'Download' operation
Protip: Do a 'Check' operation before you do 'Refresh' operation
To fetch Info about a video, right-click it.
To Tidy the data directory, use the main menu (or right-click a channel/playlist/folder).
youtube-dl offers a large number of download options. This is how to set them.
- Click Edit > General download options...
A new window opens. Any changes you make in this window aren't actually applied until you click the 'Apply' or 'OK' buttons.
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.
At the moment, the general download options apply to all the videos, channels, playlists and folders you've added.
Now, suppose you want to apply some download options to the Music folder:
- Right-click the folder, and select Apply download options...
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.
Now, suppose you want to add a different set of download options, but only for the channel The Beatles.
- Right-click the channel, and select Apply download options...
- In the new window, click the 'OK' button
The previous set of download options still applies to everything in the Music folder, except the channel The Beatles.
By default, Tartube downloads videos as quickly as possible using each video's original web 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
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
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.
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.
- Click Edit > System preferences... > Operations > Custom
- Click In custom downloads, apply a delay after each video/channel/playlist download to select it
- Select the maximum delay
- If you also set a minimum delay, Tartube uses a random value between these two numbers
- You can now start the custom download
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 you've downloaded a video, you can watch it by clicking the word Player.
If you haven't downloaded the video yet, you can watch it online by clicking the word Website or YouTube. (One or the other will be visible).
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.
Beneath the videos you'll find a toolbar. The buttons are self-explanatory, except for the one on the right.
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.
- 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
You can mark videos, channels, playlists and folders that you find interesting, or which are important.
- You can bookmark a video
- 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.
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.
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 Edit > General download options... > Files > Filesystem
- 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).
You can tell Tartube to automatically delete videos after some period of time. This is useful if you don't have an infinitely large hard drive.
- Click Edit > System preferences... > Filesystem > Video Deletion
- 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.
Tartube is a GUI front-end for youtube-dl, 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
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
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.
- Click Media > Import into database > JSON export file or Media > Import into database > Plain text export file
- Select the export file you created earlier
- A dialogue window will appear. You can choose how much of the database you want to import
Tartube can automatically extract the audio from its downloaded videos, if that's what you want.
The first step is to make sure that either FFmpeg or AVconv is installed on your system - see 6.4 Setting the location of FFmpeg / AVconv.
The remaining steps are simple:
- In Tartube's main window, click Edit > General download options...
In the new window, if the Sound only tab is visible, do this:
- Click the Sound Only tab
- Select the checkbox Download each video, extract the sound, and then discard the original videos
- In the boxes below, select an audio format and an audio quality
- Click the OK button at the bottom of the window to apply your changes
If the Post-process tab is visible, do this:
- Click on the Post-process tab
- Select the checkbox Post-process video files to convert them to audio-only files
- If you want, click the button Keep video file after post-processing it to select it
- In the box labelled Audio format of the post-processed file, specify what type of audio file you want - .mp3, .wav, etc
- Click the OK button at the bottom of the window to apply your changes
N.B. Many video websites, such as YouTube, allow you to download the audio (in .m4a format) directly, without downloading the whole video, and without using FFmpeg or AVconv.
- In Tartube's main window, click Edit > General download options... > Formats
- In the list on the left-hand side, select an .m4a format
- Click the Add format >>> button to add it to the list
- Click the OK button at the bottom of the window to apply your changes
Tartube compiles a database of the videos, channels and playlists it has downloaded.
If you want something simpler, then you can click the Classic Mode Tab for an interface that looks just like youtube-dl-gui.
- Copy and paste the URLs of videos, channels and/or playlists into the box at the top
- Click the + button to select a directory (folder). All the videos are downloaded into this directory
- Select a video or audio format, or leave the Default setting enabled
- Click the Add URLs button
- If you like, you can add more videos/channels/playlists, using a different directory and/or a different format
- When you're ready, click the Download all button
Tartube doesn't add any of these videos to its database. When you restart Tartube, all of the URLs will be gone. However, the videos themselves will still be on your hard drive.
Because the videos aren't in a database, you can move them anywhere you want (once you've finished downloading them).
PROTIP: If you only use this tab, you can tell Tartube to open it automatically. Click Edit > System preferences... > Windows > Tabs and select When Tartube starts, automatically open the Classic Mode Tab.
Since v2.1.0, Tartube has been able to detect livestreams, and to notify you when they start.
This feature is EXPERIMENTAL, has only been tested on YouTube, and may not work as intended.
Livestream detection does not work at all on 32-bit MS Windows.
Tartube searches for livestreams whenever you check or download channels and playlists.
Livestreams are easy to spot. A livestream that hasn't started yet has a red background. A livestream that's streaming now has a green background. (Livestreams that have stopped broadcasting have a normal background.)
Every few minutes, Tartube checks whether a livestream has started or stopped. This happens automatically in the background; there is no need for you to do anything.
You can modify how often livestreams are checked (and whether they are checked at all). Click Livestreams > Livestream preferences....
For technical reasons, there are practical limits to what Tartube can detect. On busy channels, Tartube may not be able to detect livestreams that were announced some time ago. Even if you change the number of days from 7 to a very large number, there is no guarantee that Tartube will detect everything. (If you change the value to 0, Tartube will only detect livestreams that are listed before any ordinary videos.)
By default, Tartube checks a livestream every three minutes, waiting for it to start (or stop). Decreasing this period might not be a good idea; it's possible that the website will think you are spamming.
If you keep missing the start of your favourite livetreams, pester the creators until they add a short countdown. If you want to force a check, in the main window click Livestreams > Update existing livestreams.
A Tartube installation includes a number of sound effects. You can choose the one you want to use as an alarm. If you want to add your own sound effects, find the directory (folder) where Tartube is installed, copy the new .mp3 or .wav files into ../sounds, and restart Tartube.
Tartube can notify you when a livestream starts. (Desktop notifications do not work on MS Windows yet.)
The preferences window shows the actions Tartube takes by default. These preference are applied to a livestream as soon as it is detected.
Most users will prefer to leave the checkboxes unselected, and instead set up notifications only for the livestreams they want to see.
- Click Notify to show a desktop notification when the stream starts (does not work on MS Windows)
- Click Alarm to sound an alarm when the stream starts
- Click Open to open the stream in your web browser as soon as it starts
- If you think the stream might be removed from the website, you can click D/L on start or D/L on stop. If you click both of them, Tartube will download the video twice. (Think of the first one as a backup, in case the second download doesn't succeed.)
To disable any of these actions, simply click the same label again.
NOTE: At the time of writing (April 2020), youtube-dl cannot download livestreams while they are broadcasting. Hopefully this is a youtube-dl issue that will be fixed in due course.
Tartube's livestream detection has only been tested on YouTube. It's possible that it might work on other websites, if they behave in the same way. Here is how to set it up.
Firstly, find the RSS feed for the channel or playlist. You may have to use a search engine to find out how to do that. (For YouTube channels/playlists, Tartube finds the feed for you automatically.)
Secondly, right-click the channel and select Show > Channel properties... (alternatively, right-click a playlist and select Show > Playlist properties...
Now click the RSS feed tab. Enter the address (URL) of the RSS feed in the box. Click the OK button to close the window.
- 7.1 Tartube won't install/won't run/doesn't work
- 7.2 Tartube crashes a lot
- 7.3 "Download did not start" error
- 7.4 Can't download a video
- 7.5 Downloads never finish
- 7.6 Videos are missing after a crash
- 7.7 'Check all' button takes too long
- 7.8 'Download all' button takes too long
- 7.9 Videos downloaded to inconvenient location
- 7.10 Tartube database file is getting in the way
- 7.11 Duplicate video names
- 7.12 Convert video to audio
- 7.13 FFmpeg fails to merge video/audio into single file
- 7.14 Too many folders in the main window
- 7.15 Not enough videos in the main window
- 7.16 Toolbar is too small
- 7.17 YouTube name/password not accepted
- 7.18 Georestriction workarounds don't work
- 7.19 MS Windows installer is too big
- 7.20 Tartube can't detect livestreams
- 7.21 Livestream start time not visible
- 7.22 Livestream is already finished
- 7.23 Can't hear livestream alarms
- 7.24 British spelling
- 7.25 No puedo hablar inglés
Q: I can't install Tartube / I can't run Tartube / Tartube doesn't work properly!
A: Please report any problems to the authors at our Github page.
A: Tartube is known to fail on Windows 7 systems that have not been updated for some time. The solution is to install this patch from Microsoft. The simplest way to install the patch is to let Windows update itself, as normal.
A: On Linux, if the DEB or RPM package doesn't work, try installing via PyPI.
Q: I can install and run Tartube, but it keeps crashing!
A: Tartube uses the Gtk graphics library. This library is notoriously unreliable and may even cause crashes.
If stability is a problem, you can disable some minor cosmetic features. Tartube's functionality is not affected. You can do anything, even when the cosmetic features are disabled.
- Click Edit > System preferences... > General > Stability
- Click Assume that Gtk is broken, and disable those features anyway to select it
Another option is to reduce the number of simultaneous downloads. (On crash-prone systems, two simultaneous downloads seems to be safe, but four is rather less safe.)
- In the main window, click the Progress Tab
- At the bottom of the tab, click the Max downloads checkbutton to select it, and reduce the number of simultaneous downloads to 1 or 2
- (It's not necessary to reduce the download speed; this has no effect on stability)
Q: When I try to download videos, nothing happens! In the Errors/Warnings tab, I can see "Download did not start"!
A: See 6.3 Setting youtube-dl's location
Q: I can't download my favourite video!
A: Make sure youtube-dl is updated; see 6.2 Check youtube-dl is updated
Before submitting a bug report, 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 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 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
Q: I clicked the 'Download all' button and it starts, but never finishes!
A: This generally indicates an error in the Python, Gtk and/or Tartube code. If you're running Tartube from a terminal window, you should be able to see the error, which you can report on our GitHub page.
There are two things you can try in the meantime:
- Click Edit > System preferences... > General > Modules, and select the Assume that Gtk is broken, and disable some features box
- Click Edit > System preferences... > Filesystem > DB Errors, and then click the Check button
Q: After I downloaded some videos, Tartube crashed, and now all my videos are missing!
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
- In the data directory is the broken tartube.db file. You should rename to something else, in case you want to examine it later
- In the same directory, you might be able to see a directory called .backups
- If .backups is not visible, then it is hidden. (On many Linux/BSD system, pressing CTRL + H will reveal hidden folders)
- Inside the .backups directory, you'll find some backup copies of the database file
- Choose the most recent one, copy it into the directory above, and rename the copy as tartube.db, replacing the old broken file
- Restart Tartube
- Click the Check All button. Tartube will update its database with any videos you've downloaded that were not in the backup database file
Tartube can make more frequent backups of your database file, if you want. See the options in Edit > System preferences... > Filesystem > Backups.
Note that Tartube does not create backup copies of the videos you've downloaded. That is your responsibility!
Q: I clicked the 'Check all' button, but the operation takes so long! It only found two new videos!
A: By default, the underlying youtube-dl software checks an entire channel, even if it contains hundreds of videos.
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.
- Click Edit > System preferences... > Operations > Performance
- Select the checkbox Stop checking/downloading a channel/playlist when it starts sending vidoes we already have
- In the Stop after this many videos (when checking) box, enter the value 3
- In the Stop after this many videos (when downloading) box, enter the value 3
- Click OK to close the window
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: Tartube stores its database file in the same place as its videos. Why can't I store them in different places?
A: This question has been asked by several people who were storing their videos on some remote filesystem (perhaps in the so-called 'cloud'). They found that the videos could be downloaded to that remote location, but that Tartube couldn't save its database file there.
At the moment, the answer is "Tartube is working fine, fix your own computer". Perhaps in the future, someone will think of an urgent need for the database file and the data folder to be split up. Until then, there are a number of good reasons for keeping them together:
- If the database file exists in the folder, Tartube can be confident that it's downloading videos to the place you actually intended
- If Tartube can't read/write its own database file, that probably means that it won't be possible to store any videos, thumbnails, descriptions, and so on
- Tartube actually creates a number of temporary files at this location, most of which are invisible but need to be in the same place as the videos
- If you want to move your videos from one location to another, it's easy - just move a single directory (folder) and everything it contains. There is no need to reconfigure anything; just tell Tartube where to find the new directory (folder)
- Splitting up the data folder and the database file would require a lot of code to be rewritten, and this would probably introduce lots of new bugs
Q: I downloaded a channel, but some of the videos in the channel have the same name. Tartube only downloads one of them!
A: Tartube can save the video files using a multitude of different filename formats. Video names might be identical, but the video IDs are unique, so you can add the ID to the filename.
- Click Edit > General download options... > Files > File names
- In the box Format for video file names, select Title + ID
- Click OK to close the window
Q: I want to convert the video files to audio files!
A: See 6.20 Converting to audio
Q: I downloaded a video and expected a single video file, instead Tartube downloaded several files, none of which are playable!
Q: I set the download option 'If a merge is required after post-processing, output to this format', but it doesn't work!
A: The solution to both problems is to install FFmpeg, and to set the output format correctly.
Firstly, make sure FFmpeg is installed on your system - see 6.4 Setting the location of FFmpeg / AVConv.
Secondly, set your desired output format. Open the Download options window (for example, click Edit > General download options... > Formats > Preferred). Add a format like mp4 to the List of preferred formats, then add the same format to If a merge is required after post-processing, output to this format.
For some reason, youtube-dl ignores the download option unless the format is specified in both places. (You will see a warning if you forget.)
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
Q: I want to see all the videos on a single page, not spread over several pages!
A: At the bottom of the Tartube window, set the page size to zero, and press ENTER.
Q: The toolbar is too small! There isn't enough room for all the buttons!
A: Click Edit > System preferences... > Windows > Main window > Don't show labels in the toolbar.
MS Windows users can already see a toolbar without labels.
Q: I added my YouTube username and password, but I am still seeing authentification errors!
A: The questioner is talking about the settings in Edit > General download options... > Advanced.
This is a youtube-dl issue. A general solution is described in this post.
The solution describes how to create a cookies.txt file, which can be specified as a download option.
Having created the file, in the same edit window, click the General tab. In the box labelled Extra youtube-dl command options, you can add:
--cookies=YT-cookies.txt
See also the Tartube thread here.
Q: I want to download a video, but it's blocked in my region. I set the geostriction workarounds, but I still can't download the video!
A: youtube-dl provides some options for bypassing region-blocking. These options are visible by clicking Edit > General download options..., then click the Show advanced download options button if it's visible, then click the tabs Advanced > Geo-restriction.
Unfortunately, although these options exist, websites are not compelled to respect them. YouTube, in particular, will completely ignore them.
In many cases, the only remedy is to pay for a subscription to a VPN.
Q: Why is the Windows installer so big?
A: 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:
C:\Users\YOURNAME\AppData\Local\Tartube\msys64\home\user\tartube\nsis
The scripts contain full instructions, so you should be able to create your own installer, and compare it with the official one.
Q: Tartube can't detect upcoming livestreams at all!
A: Livestream detection is experimental, has only been tested on YouTube, and may not be reliable. It does not work at all on 32-bit MS Windows. See 6.22 Livestreams.
A: Click Edit > System preferences... General > Modules.
If the Python feedparser module is not available, you can install it via PyPI. On Linux/BSD, the command to use is something like:
pip3 install feedparser
The Tartube installer for 64-bit MS Windows already contains a copy of feedparser, so there is no need to install it again.
Q: Why doesn't **Tartube* show the start time for livestreams?*
A: Popular video websites like YouTube do not provide that information.
Q: Tartube is showing a livestream that finished hours/days/centuries ago!
A: Right-click the video and select Livestream > Not a livestream.
Q: I set an alarm for an upcoming livestream, but I didn't hear anything!
A: Obviously you have already checked that your speakers are turned on, so now click Edit > System preferences... General > Modules.
If the Python playsound module is not available, you can install it via PyPI. On Linux/BSD, the command to use is something like:
pip3 install playsound
The Tartube installer for 64-bit MS Windows already contains a copy of playsound, so there is no need to install it again.
Q: These British spellings are getting on my nerves!
A: Click Edit > System preferences.... Click the drop-down box and select American English, and then restart Tartube
Q: ¡No puedo usar YouTube porque no hablo inglés!
A: Necesitamos más traductores.
If you would like to contribute a translation of this project, please read this document.
- Report a bug: Use the Github issues page
See the AUTHORS file.
Tartube is licensed under the GNU General Public License v3.0.
✨🍰✨