wp-fedistream/README.md

# WP FediStream

Stream music over ActivityPub - Build your own music streaming platform for Musicians and Labels.

[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](CHANGELOG.md)
[![PHP](https://img.shields.io/badge/PHP-%3E%3D8.3-purple.svg)](https://php.net)
[![WordPress](https://img.shields.io/badge/WordPress-%3E%3D6.4-blue.svg)](https://wordpress.org)
[![License](https://img.shields.io/badge/license-GPL--2.0%2B-green.svg)](https://www.gnu.org/licenses/gpl-2.0.html)

## Description

WP FediStream is a WordPress plugin that enables musicians, bands, and labels to create their own music streaming platform. It leverages the ActivityPub protocol to connect with the Fediverse, allowing artists to share their music with followers across Mastodon, Pixelfed, and other federated platforms.

**This project is proudly "vibe-coded" using Claude AI** - the entire codebase was created through AI assistance.

### Key Features

- **Artist Management** - Create profiles for solo artists, bands, duos, and collectives
- **Album/Release Management** - Organize music into albums, EPs, singles, and compilations
- **Track Management** - Upload and manage individual tracks with full metadata support
- **Playlist Creation** - Curate playlists with drag-and-drop track ordering
- **Audio Player** - Full-featured player with queue, shuffle, repeat, and volume controls
- **Genre & Mood Taxonomies** - Organize music by genre and mood for easy discovery
- **Licensing Options** - Support for Creative Commons and traditional copyright
- **ActivityPub Integration** - Share releases to the Fediverse with full actor support
- **WooCommerce Integration** - Sell music directly from your site with custom product types
- **User Library** - Favorites, artist follows, and listening history
- **Notifications** - In-app and email notifications for new releases and interactions

## Requirements

- PHP 8.3 or higher
- WordPress 6.4 or higher
- Composer (for development/installation)

### Optional

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

## Installation

### From Source

1. Clone or download the repository to your WordPress plugins directory:

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

2. Install Composer dependencies:

   ```bash
   cd wp-fedistream
   composer install --no-dev
   ```

3. Activate the plugin in WordPress admin under **Plugins > Installed Plugins**

4. Navigate to **FediStream** in the admin menu to get started

## Usage

### Getting Started

1. **Add Artists** - Create profiles for your artists or bands
2. **Create Albums** - Set up albums and assign them to artists
3. **Upload Tracks** - Add tracks to albums with audio files
4. **Create Playlists** - Curate collections of tracks
5. **Share via ActivityPub** - Publish releases to the Fediverse and gain followers

### Custom Post Types

| Post Type | Description | URL Slug |
|-----------|-------------|----------|
| Artist | Musicians, bands, collectives | `/artists/` |
| Album | Albums, EPs, singles, compilations | `/albums/` |
| Track | Individual audio tracks | `/tracks/` |
| Playlist | Curated track collections | `/playlists/` |

### Taxonomies

| Taxonomy | Type | Description |
|----------|------|-------------|
| Genre | Hierarchical | Music genres (Rock > Indie Rock) |
| Mood | Non-hierarchical | Track/playlist moods (Energetic, Calm) |
| License | Hierarchical | Copyright and Creative Commons licenses |

### Shortcodes

| Shortcode | Description |
|-----------|-------------|
| `[fedistream_artist id="123"]` | Display artist profile |
| `[fedistream_album id="456"]` | Display album with tracklist |
| `[fedistream_track id="789"]` | Display track with player |
| `[fedistream_playlist id="101"]` | Display playlist with tracks |
| `[fedistream_latest_releases]` | Recent releases grid |
| `[fedistream_popular_tracks]` | Popular tracks list |
| `[fedistream_player]` | Audio player widget |
| `[fedistream_library]` | User library page |

### User Roles

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

## File Structure

```txt
wp-fedistream/
├── assets/
│   ├── css/           # Stylesheets
│   ├── js/            # JavaScript
│   └── images/        # Images
├── includes/
│   ├── ActivityPub/   # ActivityPub integration
│   ├── Admin/         # Admin interface classes
│   ├── Frontend/      # Frontend components
│   ├── PostTypes/     # Custom post type classes
│   ├── Taxonomies/    # Custom taxonomy classes
│   ├── Roles/         # User roles and capabilities
│   ├── User/          # User library and notifications
│   ├── WooCommerce/   # WooCommerce integration
│   ├── Plugin.php     # Main plugin singleton
│   └── Installer.php  # Activation/deactivation
├── languages/         # Translation files
├── templates/         # Twig templates
├── vendor/            # Composer dependencies
├── CHANGELOG.md       # Version history
└── wp-fedistream.php  # Plugin entry point
```

## Contributing

This project is in early development. Contributions, bug reports, and feature requests are welcome.

- **Repository:** <https://src.bundespruefstelle.ch/magdev/wp-fedistream>
- **Issues:** <https://src.bundespruefstelle.ch/magdev/wp-fedistream/issues>

## License

This project is licensed under the GPL v2 or later.

## Author

**Marco Graetsch**

- Website: <https://src.bundespruefstelle.ch/magdev>
- Email: <magdev3.0@gmail.com>

---

*Built with Claude AI*