=== Nucleus Audio Playlist ===
Contributors: nucleusdigital
Tags: audio player, music player, playlist, mp3, waveform
Requires at least: 5.6
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A modern, self-hosted HTML5 audio player for WordPress. Drop MP3s in a folder, add a shortcode, and play.

== Description ==

**Audio Playlist** is a modern, self-hosted HTML5 audio player for WordPress. It dynamically reads MP3 and WAV files from a folder on your server — no Spotify, no SoundCloud, no dependency on external music services.

= Features =

* Reads tracks automatically from your audio folder
* Displays track titles based on filenames (clean formatting with spaces and capitalization)
* Displays a cover image (cover.jpg or cover.png) for the playlist
* Renders an interactive waveform powered by WaveSurfer.js
* Full playback controls: Play, Pause, Previous, Next, Shuffle, Loop, Volume
* Auto-scrolling title for long track names
* Works in any shortcode-compatible field — no Gutenberg block required
* Compatible with Divi and other page builders
* Configurable background color for the player

= Usage =

Place your MP3 files in a folder named `playlist` under your audio base directory, add a `cover.jpg`, then use the shortcode:

`[nuclaup_playlist label="My Playlist"]`

= Free version limitations =

* Reads tracks from a single fixed folder named `playlist`
* Single cover image per playlist (cover.jpg) — no per-track covers

= Pro version =

**Audio Playlist Pro** adds:

* Multiple playlists with custom folder paths
* ID3 tag reading (title, artist) for accurate track metadata
* Per-track cover art via catalog code matching
* Companion Python script to extract and resize cover art from MP3 ID3 tags
* Advanced admin panel with catalog code configuration

== Installation ==

1. Upload the `audio-playlist` folder to `/wp-content/plugins/`
2. Activate the plugin from **Plugins → Installed Plugins**
3. Open **Audio Playlist** from the WordPress sidebar
4. If your audio folder is named `audio` and is located in the root of your site, no configuration is needed — the plugin works automatically.

= Folder structure =

Place your audio files like this:

`/audio/playlist/track01.mp3`
`/audio/playlist/track02.mp3`
`/audio/playlist/cover.jpg`

Then use the shortcode `[nuclaup_playlist label="My Playlist"]` anywhere.

== Frequently Asked Questions ==

= Do I need to configure anything? =

No. If your audio folder is named `audio` and is in the root of your site, the plugin works out of the box.

= Why does the shortcode not have a folder parameter? =

The free version reads from a single fixed folder (`playlist`) by design. The Pro version allows custom folder paths and multiple independent playlists.

= What if I use multiple shortcodes on the same page? =

They will all display the same playlist, since the free version uses a single fixed folder.

= What image formats are supported for cover art? =

JPG and PNG. Name the file `cover.jpg` or `cover.png` and place it in the playlist folder.

= Does it work with Divi? =

Yes. A dedicated Divi Integration tab inside the plugin provides ready-to-paste CSS to fix any style conflicts.

= Does it work on shared hosting? =

Yes. The plugin uses WordPress native functions and does not require CLI access.

= Can I change the player background color? =

Yes, from the plugin's Settings tab in the WordPress admin.

== Screenshots ==

1. The player with waveform, cover art, and track list
2. Admin panel — Settings tab
3. Admin panel — Divi Integration tab

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
