Funkwhale 2.0 Alpha candidate

Hello dear community,

We are happy to announce that we will release an alpha candidate for Funkwhale 2 soon! This second version of Funkwhale brings significant changes and enhancements. However, to achieve this, we had to introduce breaking changes, including a brand-new API (version 2). This means your v2 pod will not be able to federate with v1 pods. 🚨

⚠️ Migration & Testing

We need to test the migration from v1 to v2 on real servers. There is a risk of data loss—you may need to restore or manually edit the database. If you want to test the alpha release, make sure to backup your data and be prepared for troubleshooting!

This update completely changes the Funkwhale user experience. There will be bugs—what we’re doing is new, and we are not aware of any other software facing similar federation challenges. Thanks to NLnet for their funding support, which made this possible! 🎉 Many of us worked on this in our free time, so any help is appreciated! 💜

✨ New Features

A complete list of features will be in the changelog, but here are the most important ones:

New UI with both dark and light themes (still in progress, expect some bugs).
Multiple artist support for compilations and featured tracks.
Follow users to track their listening activity, favorites, and playlists.
Listenbrainz integration to sync listenings and favorites.
Admin option to allow only MusicBrainz-tagged files on an instance.
Content quality filter.
Libraries are replaced with playlists for a better user experience.

🚨 Breaking Changes

New ArtistCredit object: Albums and tracks now support multiple artists.
Libraries removed: They have been replaced with playlists. Existing libraries will be converted into playlists, and library follows will become playlist follows.

❗ Federation Impact

Your v2 pod will NOT federate with v1 pods.
This could lead to unexpected issues.
If you and a friend both run instances, testing the migration on both will provide valuable feedback for development.
Please report bugs or submit fixes via merge requests!

🛠️ Technical Considerations

This section is for ActivityPub developers or anyone interested in the internal changes.

Why Did We Remove Libraries?

Funkwhale’s data model has always been complex. Some key points:

Tracks are only metadata; Uploads manage audio files.
Users do not own track metadata, only the audio files.
Multiple users can rely on the same metadata.
A track may become unplayable if all uploads for it disappear.
Libraries historically managed file ownership and sharing via federation.

Problems with Libraries

Users found Libraries confusing because they were: - Used to "follow" remote content but lacked a feed. - Used to "follow" user content but not their activities. - Used for discovering remote content (sharing audio + metadata). - Managing privacy levels of audio files. - Sometimes used as playlists.

Solution: Playlists Replace Libraries

Playlists are now linked to Libraries as an abstraction.
Libraries are now just an access control system (3 levels: private, same pod, federated).
User follows are now possible to track listening activity.

User Experience Changes

You can add any track to a playlist—even if you don’t own the file.
Playlists remain stable, even if files disappear from the network.
Sharing a playlist shares only metadata, not files.
To share files, users must request access via the playlist (behind the hood this is a Follow request to playlist.library)
Playlist visibility ≠ file visibility (e.g., a public playlist may contain private uploads).
Metadata in playlists is always public., but the playslit can be private.

Why This Change?

Simplifies the data model and reduces maintenance complexity.
UI improvements: Maintaining both Libraries & Playlists would require too much work.
We anticipate some user confusion, but we can introduce UI enhancements to clarify sharing rules (e.g., badges showing which tracks a user owns).

💡 Looking Ahead

We are excited to see how this update evolves! 🚀 If you encounter issues, report them or submit fixes. Let’s build Funkwhale 2 together! 💜

Happy listening! 🎶