You've already forked wp-fedistream
feat: Add plugin action links and user guide
- Add Settings and Dashboard links to the WordPress Plugins page - Create comprehensive user guide (USERGUIDE.md) covering: - Installation and configuration - Managing artists, albums, tracks, and playlists - Shortcodes and widgets - ActivityPub and WooCommerce integration - User library features and troubleshooting Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
550
USERGUIDE.md
Normal file
550
USERGUIDE.md
Normal file
@@ -0,0 +1,550 @@
|
||||
# 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
|
||||
|
||||
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
|
||||
|
||||
- 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).*
|
||||
Reference in New Issue
Block a user