Behind the Scenes: Rewrite Updates and Release Strategy

Hey everyone! It's been a while since I've given a proper update and boy is there a lot to update on. For today's Behind the Scenes, I will be talking about my plans for the full release of rewrite as well as the recent updates that we have within the rewrite itself. There's enough content here that I could probably write 2 articles on everything. Having said that, I'll instead just give one giant article on everything, so here we go!

Release Plans / Strategy

At this point, the UI for the main Invidious instance has closed their doors. Their API is still running which means that anyone using the live release of FreeTube should still be able to make use of the main Invidious instance. Even then, that doesn't mean that we'll get to keep using it for much longer. To tie in with the shut down of the Invidious API on the main instance, I'm pleased to announce the release date of the FreeTube rewrite.

The rewrite of FreeTube will be officially released on October 2nd, 2020

This should allow a transition to the new version while also allowing me to focus on any potential bug fixes that may occur during the first few hours of release. I will do my best to keep this release date. I do not foresee any major issues coming up that will delay this release, but I will make sure everyone is aware if we do have to push it back.

So What will be Changed?

I need to go ahead and get this out of the way, because this is a very important change and every single person needs to be aware of it.

Your data WILL NOT carry over to the rewrite

This includes everything. Your settings, history, profiles, and even subscriptions will not be carrying over to the rewrite release.

I know, I know, this sounds pretty bad, however let me explain my reasoning.

The rewrite includes major data structure changes, where the data objects within the current version just won't fit the same structure within the rewrite. It's very possible to convert your data into the new format. While I could include this functionality within FreeTube, I have opted to not do so.

Backwards compatibility is a wonderful thing. It makes transitions easier to handle as a user and ensures that you can get up and running in the quickest way possible. Having said that, if I include backwards compatibility with the live data structure, there will never be a clear cut time on how long I should keep that. The live release has a lot of structural changes that handle backwards compatibility from previous releases and now feels like a good time to get rid of a majority of that and start fresh. I want to be able to move forward without worrying too much about backwards compatibility. While this could be a slight problem for everyone in the short term, I believe it will be better for the long term.

So what can you do? As for subscriptions, you can use the built in export functionality to export your subscriptions in an OPML or NewPipe format and those formats will be supported for importing in the rewrite. These formats will not carry over your profiles though.

If you do want to carry over your profiles, you will need to use the FreeTube export format. By default, this format will not import into the rewrite and will need to be convert. While the conversion logic won't be within FreeTube itself, there is a solution.

A member of our community has been kind enough to put together a working script to convert your live FreeTube subscriptions into a usable file to import your subscriptions into the rewrite. You can find more information about the script here and all credit goes to GilgusMaximus for putting this script together.

For exporting anything else, you have probably noticed that no option is available in the current settings. When you install the rewrite, non of this data will be removed, however you won't be able to find it within the app. If you go to this comment that I have made on GitHub, I have listed out the file locations for all of the data saved by FreeTube. From there, you can manually copy those files to another location of your desktop so that we can convert them in the near future. The exact files you want to look for are savedvideos.db, subscriptions.db, and videohistory.db. settings.db is also available, however I wouldn't imagine it being as needed to grab this file as well.

Settings Changes

As you may be curious, some of the settings options will be changed in the rewrite and I'd like to go over those changes.

The first big settings change will be the default Invidious instance. Obviously with the main Invidious instance shutting down, will not be able to be used as the default instance. For future releases, the new default will be I have already asked and received permission from the maintainer to use their instance as the default and a big thanks to Perflyst for giving me permission.

The other big default change will be the API preference. The local API will become the new default for data retrieval within FreeTube. Myself as well as others in out Matrix community, have been using the local API on a near daily basis at this point with very few issues. It is clear that it is stable enough to be the default API moving forward. Fallback mode will be enabled by default as well which means that any failure with the local API will automatically fallback to the Invidious equivalent in an attempt to retrieve the information you need. It is very easy to disable this fallback or swap your API preference if you so desired.

Missing Features

With the initial release of the rewrite, there will be a few features missing from the live release that won't make it in time. I'd like to go over them here.

The biggest one is going to be the Favorites functionality. I could probably make a quick equivalent before the release, however I want to do something better and don't want to deal with any backwards compatibility when I remove that functionality. I want this feature to be replaced with full local playlists support and I won't have enough time to get it done.

Another big one is going to be Tor / Proxy support. It's just another case of me not having enough time to get to it, so this likely won't be included either. This one may be able to squeeze into the release depending on how fast I can get everything else done, but I'm not going to promise it's availability just to be safe. If this is a deal breaker for you, I highly recommend using a VPN while using FreeTube as a substitute.

Distraction Free mode will also not be available. This functionality has been very basic to begin with, however I'd like to include an advanced version of this feature. Instead of me picking what to hide in this mode, I'd like to make it up to the user to decide what to include and what not to include within the UI. This will be easy to do with the new code base however like the other features I simply haven't had time to get to it.

Resolutions above 1080p will also be missing in videos. There is an issue with the new video player where it doesn't display these higher quality formats for some reason and it's something I want to look into. Once more, this is something that I haven't been able to have time to get to.

When we are past the initial release, these will be the first features that I focus on so that I can get them available as soon as possible. I understand that these are features used a lot by users so I will do my best to get them ready quickly.

Version Number

When I set off to work on this rewrite, my initial plan was that the finished build of this rewrite would be considered v1.0.0. A v1.0.0 release is a huge milestone for any project and symbolizes that a project has all core features as well as being very stable. While I think we've nailed the stable part, we still have a little ways to go to reach the “has all core features” part of that definition.

Up to this point in development, I have been calling the rewrite v0.8.0. While that version number doesn't really reflect the amount of work that's gone into this rewrite, it does reflect the idea that it's the next iteration of FreeTube and that it's not yet at a finished state. I will likely be keeping this version number with the initial release of the rewrite, however I would expect a v1.0.0 release to soon follow. I imagine a few people were curious on what the rewrite will be called so I figured I'd answer that here.

Available Builds

FreeTube currently provides a large amount of builds. Some of you may not be aware, there are some builds that I do not publish myself, namely the Flathub and AUR builds. They are both maintained by someone else, however they are popular enough that I have included them on the main website.

Having said that, I cannot guarantee that these builds will be updated to the rewrite at the same time as the initial release. I am however interested in taking over the publishing for the Flathub release. The maintainer has already made some effort in getting the Flathub build ready to transition, however he has hit a blocker and is in need of some help. If you are familiar with the process of bundling Electron apps to Flatpak, please reach out to me as I'd like to get this put together in time. Regardless I will be spending some time trying to put this together once most of the other tasks have been complete.

Code Repository

As you know, all of the development with the rewrite has been done over on the secondary FreeTube-Vue repository. It's been nice having a dedicated space to focus on this, however we need to prepare for a transition.

I hope to transition all of the code over to the FreeTube repository that many already follow. During this transition, I will be doing my best to also include the Git history, so that those that have been contributing up to this point can still be credited for their work.

Regardless of what happens, the FreeTube-Vue repository will be archived but not deleted for those who would still like to view it.

This now leaves the question of what to do with the code in the current release. I don't want to delete it and want to archive it in some way. I could transfer everything to a new repository or I could simply keep the code in it's own branch within the main repository. I'm open to suggestions on how we'd like to do this, I don't have any strong preference one way or the other.

Updating to New Versions in the Future

Due to the nature of including a local API within FreeTube now, future updates of FreeTube will be slightly different. I will no longer be providing a full blog post for every new update. Updates will still include a small changelog that can be viewed, however it won't be the same full updates that I've been doing up to this point.

It will be more important than ever that you stay up to date with your FreeTube version. YouTube can easily change their layout at any given point and I will try to be faster in getting these changes out. If you ever see an update for FreeTube, it should probably be updated.

Rewrite Updates

Oh man, we're only half way through everything. That was everything I needed to mention for the release itself. I'd now like to go over the recent updates that has been made to the rewrite.

Local API Updates

As I mentioned earlier, the local API has been run through it's course as far as testing goes and several people within our Matrix community has been giving this some serious attention and reporting any issues that have occurred. I want to give a huge thanks to everyone that has been testings the local API recently. At this point, it is working very well.

We have also finally reached feature parity with the Invidious API. The local API now handles all features that we used within Invidious and FreeTube can now be 100% independently of Invidious. This includes the few features that were missing from last time such as grabbing channel information, Dash file generation, storyboard URL generation, and grabbing Trending information. I wanna give a huge shout out to GilgusMaximus for the help on finishing out the local API. I don't think I would have finished all of this in time without his help!

This is a huge milestone for FreeTube, and I'm really glad that we're finally at this point.

Full Localization

A huge effort has been made to include full localization within FreeTube. This has honestly been a pain having to go in and replace every single hard coded string within the app to a new string that detects the language you're using. I do think the end result is worth it as we can know have FreeTube in a variety of different languages. At the time of writing, we are on track to include at least 13 different languages with FreeTube for the first release. To me, that's extremely awesome that we can offer something such as this with our first release.

There's still time to add even more languages before the first release. If you'd like to see your language added to the first release of the FreeTube rewrite, please consider adding your language to our Weblate Page before the release deadline. I will accept any language that has translated at least 80% of all available strings within FreeTube by the time the release date has arrived.

Full Subscriptions Support

Here is the feature that a lot of people have been waiting for (as well as what I'd consider one of the flagship features of FreeTube). Subscriptions have now been fully implemented into the rewrite. This also includes the ability to sort your subscriptions within “Profiles” so that you can have a more tailored experience on which channels you'd like to see updates for.

Along with the usual API preference for subscriptions, you'll even have the option of fetching your subscriptions via an RSS feed. Both YouTube and Invidious provides an RSS feed for channels so the feed that FreeTube grabs from will depend on your API settings. RSS is a much faster option for grabbing subscriptions and is much less likely to be blocked by YouTube (which has been an issue with the public Invidious instances for a while). So if you're someone who likes to refresh your subscriptions fairly often, I would highly recommend using RSS instead of the traditional method.

Using RSS does have some small drawbacks though. To start, RSS does not provide the duration of a video, so I will be unable to provide that within your feed. It also does not indicate whether a video is currently live or not, along with if the video is a premiere. There is a little bit of information included where I can do some guess work for the later issue, however telling if it's live or not is a no go. Please keep this in mind if you enable RSS.

There's also one last change that I believe everyone will like when it comes to subscriptions. In the live release, if you were in a different profile, refreshing your subscriptions would still refresh all of the subscriptions you had, even if they weren't in your current profile. This is changed in the rewrite. Your subscriptions will only update the channels in your currently active profile, which should speed up some loading depending on how many subscriptions you have. This should be a welcoming change for those with a large list of subscriptions.

So What's Next?

There actually isn't too much left to get done. I need to add some small features to the profile functionality as well as include some notifications for new updates and new blog posts. Once those are finished, then everything should be complete for a release (minus the features I mentioned that won't be worked on of course).

I don't expect these last few features to take the rest of the time to complete. Any time left before the release date will be spent fixing any last few bugs that may have occurred because of our rapid development. We hope that we'll be able to have a nice and stable release by the time everything is put together.


I want to thank everybody who uses FreeTube for their patience while I get this rewrite together. This is shaping up to become a well put together application and I hope that you feel the same once it's out. It's just a little bit longer before the release now, however there's still a lot that needs to be done. I will be continuing my work so that the rewrite can come out in time while also being as stable as possible.

If you'd like to discuss anything related to the rewrite, the best way to do so is over in our Matrix Community. You can also find me on Mastodon and Reddit.

Take care!