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](#installation)
2. [Initial Configuration](#initial-configuration)
3. [Managing Artists](#managing-artists)
4. [Creating Albums](#creating-albums)
5. [Adding Tracks](#adding-tracks)
6. [Building Playlists](#building-playlists)
7. [Using Shortcodes](#using-shortcodes)
8. [Widgets](#widgets)
9. [ActivityPub Integration](#activitypub-integration)
10. [WooCommerce Integration](#woocommerce-integration)
11. [User Library Features](#user-library-features)
12. [Troubleshooting](#troubleshooting)

---

## Installation

### Requirements

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

### Optional Requirements

- [ActivityPub Plugin](https://wordpress.org/plugins/activitypub/) - For Fediverse integration
- [WooCommerce](https://woocommerce.com/) 10.0+ - For selling music

### From Source

1. Navigate to your WordPress plugins directory:

   ```bash
   cd wp-content/plugins/
   ```

2. Clone or download the repository:

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

3. Install Composer dependencies:

   ```bash
   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

```txt
[fedistream_artist id="123"]
```

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

**Attributes:**

- `id` (required) - Artist post ID

#### Display Album

```txt
[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

```txt
[fedistream_track id="789"]
```

Shows a single track with player controls.

**Attributes:**

- `id` (required) - Track post ID

#### Display Playlist

```txt
[fedistream_playlist id="101"]
```

Shows the playlist with all tracks and player.

**Attributes:**

- `id` (required) - Playlist post ID

#### Latest Releases

```txt
[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

```txt
[fedistream_popular_tracks count="10"]
```

Shows a list of most-played tracks.

**Attributes:**

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

#### Artists Grid

```txt
[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

```txt
[fedistream_player]
```

Shows the persistent audio player.

#### User Library

```txt
[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](https://wordpress.org/plugins/activitypub/) 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:

```txt
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](https://src.bundespruefstelle.ch/magdev/wp-fedistream/issues)
- **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](https://src.bundespruefstelle.ch/magdev/wp-fedistream).*