wp-fedistream/USERGUIDE.md

WP FediStream User Guide

A comprehensive guide to setting up and using WP FediStream, the WordPress plugin for streaming music over ActivityPub.

Table of Contents

1. Installation
2. Initial Configuration
3. Managing Artists
4. Creating Albums
5. Adding Tracks
6. Building Playlists
7. Using Shortcodes
8. Widgets
9. ActivityPub Integration
10. WooCommerce Integration
11. User Library Features
12. Troubleshooting

---

Installation

Requirements

• PHP 8.3 or higher
• WordPress 6.4 or higher
• Composer (for installation from source)

Optional Requirements

• ActivityPub Plugin - For Fediverse integration
• WooCommerce 10.0+ - For selling music

From Source

1. Navigate to your WordPress plugins directory:

   cd wp-content/plugins/
   

2. Clone or download the repository:

   git clone https://src.bundespruefstelle.ch/magdev/wp-fedistream.git
   

3. Install Composer dependencies:

   cd wp-fedistream
   composer install --no-dev
   

4. Activate the plugin in WordPress admin under Plugins > Installed Plugins

5. Navigate to FediStream in the admin menu to get started

---

Initial Configuration

After activation, configure FediStream through FediStream > Settings.

General Settings

Setting	Description	Default
ActivityPub Integration	Enable Fediverse features for sharing releases	Enabled
WooCommerce Integration	Enable selling music (requires WooCommerce)	Disabled
Max Upload Size	Maximum audio file size in MB	50 MB
Default License	Default copyright license for new uploads	All Rights Reserved

License Options

FediStream supports various licensing options:

• All Rights Reserved - Traditional copyright
• CC BY - Creative Commons Attribution
• CC BY-SA - Attribution-ShareAlike
• CC BY-NC - Attribution-NonCommercial
• CC BY-NC-SA - Attribution-NonCommercial-ShareAlike
• CC0 - Public Domain Dedication

---

Managing Artists

Artists represent musicians, bands, duos, or collectives. Each artist can have their own ActivityPub presence.

Creating an Artist

1. Go to FediStream > Artists > Add New
2. Fill in the required information:
   • Name - Artist or band name
   • Biography - Detailed description (supports rich text)
   • Featured Image - Artist photo/logo
3. Configure artist details in the meta boxes:
   • Artist Type - Solo, Band, Duo, or Collective
   • Formation Date - When the artist/band started
   • Location - City, Country
   • Website - Official website URL
4. Add social media links:
   • Mastodon, Twitter/X, Instagram, Facebook, YouTube, Spotify, Bandcamp, SoundCloud
5. For bands: Add band members with their names and roles
6. Assign genres from the Genre taxonomy
7. Publish the artist

Artist Types

Type	Description
Solo	Individual musician
Band	Group of musicians
Duo	Two-person musical act
Collective	Loose group of collaborating artists

---

Creating Albums

Albums organize your music into releases. They can be full albums, EPs, singles, or compilations.

Creating an Album

1. Go to FediStream > Albums > Add New
2. Enter the album information:
   • Title - Album name
   • Description - Album notes, liner notes, story
   • Featured Image - Album artwork (recommended: 1400x1400 pixels)
3. Configure album metadata:
   • Artist - Select the primary artist
   • Album Type - Album, EP, Single, or Compilation
   • Release Date - Official release date
   • Catalog Number - Your catalog reference (optional)
   • UPC/EAN - Universal Product Code (optional)
4. Assign genres and license
5. Publish the album

Album Types

Type	Description	Typical Track Count
Album	Full-length release	8-15 tracks
EP	Extended Play	4-6 tracks
Single	Single track release	1-3 tracks
Compilation	Collection of tracks	Varies

---

Adding Tracks

Tracks are the individual songs or audio files in your library.

Creating a Track

1. Go to FediStream > Tracks > Add New
2. Enter track information:
   • Title - Song title
   • Description - Lyrics, notes, credits
3. Upload the audio file:
   • Click Select Audio File in the Track Audio meta box
   • Supported formats: MP3, WAV, FLAC, OGG, AAC
   • Recommended: High-quality MP3 (320kbps) or FLAC
4. Configure track metadata:
   • Album - Associate with an album
   • Track Number - Position in the album
   • Disc Number - For multi-disc releases
   • Duration - Auto-detected from audio file
   • BPM - Beats per minute (optional)
   • Key - Musical key (optional)
   • ISRC - International Standard Recording Code (optional)
5. Set the featured image (track artwork, optional)
6. Assign genres, moods, and license
7. Publish the track

Audio File Guidelines

Format	Quality	Recommended For
MP3	320kbps	Web streaming
FLAC	Lossless	Downloads, archival
WAV	Uncompressed	Master files
OGG	Variable	Alternative streaming

---

Building Playlists

Playlists are curated collections of tracks, useful for themed collections or user-generated content.

Creating a Playlist

1. Go to FediStream > Playlists > Add New
2. Enter playlist information:
   • Title - Playlist name
   • Description - What the playlist is about
   • Featured Image - Playlist cover art
3. Add tracks to the playlist:
   • Use the Playlist Tracks meta box
   • Search for tracks by title
   • Click to add tracks to the playlist
   • Drag and drop to reorder tracks
4. Configure visibility:
   • Public - Visible to everyone
   • Private - Only visible to the creator
5. Assign moods (optional)
6. Publish the playlist

---

Using Shortcodes

FediStream provides shortcodes to display content anywhere in your WordPress site.

Available Shortcodes

Display Single Artist

[fedistream_artist id="123"]

Shows the artist profile with bio, image, and social links.

Attributes:

• id (required) - Artist post ID

Display Album

[fedistream_album id="456"]

Shows the album with artwork, tracklist, and play buttons.

Attributes:

• id (required) - Album post ID
• show_tracks - Show tracklist (default: true)

Display Track

[fedistream_track id="789"]

Shows a single track with player controls.

Attributes:

• id (required) - Track post ID

Display Playlist

[fedistream_playlist id="101"]

Shows the playlist with all tracks and player.

Attributes:

• id (required) - Playlist post ID

Latest Releases

[fedistream_latest_releases count="5"]

Shows a grid of recent album releases.

Attributes:

• count - Number of releases to show (default: 6)
• columns - Grid columns (default: 3)

Popular Tracks

[fedistream_popular_tracks count="10"]

Shows a list of most-played tracks.

Attributes:

• count - Number of tracks to show (default: 10)

Artists Grid

[fedistream_artists count="12" columns="4"]

Shows a grid of artists.

Attributes:

• count - Number of artists (default: 12)
• columns - Grid columns (default: 4)

Audio Player Widget

[fedistream_player]

Shows the persistent audio player.

User Library

[fedistream_library]

Shows the logged-in user's music library (favorites, followed artists, history).

---

Widgets

FediStream includes widgets for your sidebar or widget areas.

Available Widgets

Widget	Description
Recent Releases	Displays latest album releases
Popular Tracks	Shows most-played tracks
Featured Artist	Highlights a specific artist
Now Playing	Shows currently playing track

Adding Widgets

1. Go to Appearance > Widgets
2. Find FediStream widgets in the available widgets list
3. Drag to your desired widget area
4. Configure the widget options
5. Save

---

ActivityPub Integration

FediStream integrates with the Fediverse through ActivityPub, allowing your artists to be followed from Mastodon, Pixelfed, and other platforms.

Requirements for ActivityPub integration

Install and activate the ActivityPub plugin from WordPress.org.

How It Works

1. Each artist becomes an ActivityPub actor (like a Mastodon account)
2. Fediverse users can follow artists using their handle: @artist-slug@your-domain.com
3. When you publish new albums or tracks, announcements are sent to followers
4. Followers can like and boost your releases, which shows on your site

Artist Discovery (Webfinger)

Artists can be discovered via Webfinger:

https://your-site.com/.well-known/webfinger?resource=acct:artist-name@your-site.com

Activity Types

Activity	When Sent
Create	New album or track published
Update	Album or track updated
Delete	Content removed
Follow/Accept	New follower confirmed

Viewing Followers

Artist followers are displayed on the artist's admin page under the Followers meta box.

---

WooCommerce Integration

Sell your music directly through your WordPress site using WooCommerce.

Requirements for WooCommerce Integration

• WooCommerce 10.0 or higher installed and activated
• WooCommerce integration enabled in FediStream settings

Setting Up Products

1. Enable WooCommerce in FediStream > Settings
2. Go to Products > Add New
3. Select product type:
   • FediStream Album - Sell a complete album
   • FediStream Track - Sell individual tracks
4. Configure the FediStream tab:
   • Link to the corresponding album or track
   • Set pricing type (Fixed, Pay What You Want, Name Your Price)
   • Configure minimum and suggested prices for PWYW
   • Select available download formats
   • Enable streaming access for purchasers
5. Publish the product

Pricing Types

Type	Description
Fixed	Standard fixed price
Pay What You Want (PWYW)	Customer chooses price above minimum
Name Your Price (NYP)	Customer sets any price (including free)

Download Formats

Customers can download purchased music in these formats:

• MP3 (320kbps)
• FLAC (Lossless)
• WAV (Uncompressed)
• AAC (256kbps)
• OGG Vorbis

Streaming Access

When "Include Streaming" is enabled:

• Non-purchasers hear 30-second previews
• Purchasers get full-quality streaming access
• Access is tied to the customer account

---

User Library Features

Logged-in users can build their personal music library.

Favorites

• Click the heart icon on any track, album, or playlist to save it
• View all favorites in the Library page

Following Artists

• Click "Follow" on any artist profile
• Get notified when they release new music

Listening History

• Automatically tracks what you've listened to
• View recent plays in the Library page
• Option to clear history

Notifications

Users receive notifications for:

• New releases from followed artists
• New followers (for artists)
• Fediverse interactions (likes, boosts)
• Purchases (for WooCommerce)

Notifications appear in the admin bar and can be configured for email delivery.

---

Troubleshooting

Audio Files Not Playing

1. Verify the audio file is properly uploaded
2. Check browser console for errors
3. Ensure the audio format is supported
4. Verify file permissions on the server

ActivityPub Not Working

1. Ensure the ActivityPub plugin is installed and active
2. Check that ActivityPub is enabled in FediStream settings
3. Verify your site's SSL certificate is valid
4. Check that .well-known/webfinger is accessible

WooCommerce Products Not Showing

1. Ensure WooCommerce is installed and activated
2. Enable WooCommerce in FediStream settings
3. Clear any caching plugins
4. Check for JavaScript errors in browser console

Images Not Displaying

1. Check that featured images are set on posts
2. Verify the Media Library has the images
3. Check theme compatibility with featured images
4. Regenerate thumbnails if image sizes are wrong

Performance Issues

1. Consider using a caching plugin
2. Optimize images before upload
3. Use a CDN for audio files
4. Enable object caching if available

Getting Help

• Documentation: Check this guide and the README
• Issues: Report bugs at the issue tracker
• Updates: Keep the plugin updated for latest fixes

---

Quick Reference

URL Slugs

Content Type	URL Pattern
Artists	/artists/{slug}/
Albums	/albums/{slug}/
Tracks	/tracks/{slug}/
Playlists	/playlists/{slug}/
Genres	/genre/{slug}/
Moods	/mood/{slug}/

User Roles

Role	Capabilities
FediStream Artist	Manage own content, upload files, view own stats
FediStream Label	Manage all content, manage taxonomies, view all stats

Keyboard Shortcuts (Player)

Key	Action
Space	Play/Pause
Left Arrow	Previous track
Right Arrow	Next track
Up Arrow	Volume up
Down Arrow	Volume down
M	Mute/Unmute
S	Shuffle toggle
R	Repeat mode cycle

---

For more information, visit the project repository.