=== Valacuhi MP3 Player ===
Contributors: valacuhi
Tags: audio, mp3, music player, album, playlist
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 0.4.6
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A lightweight MP3 album player with metadata extraction, embedded artwork, download buttons and download counters.

== Description ==
Valacuhi MP3 Player helps musicians and creators publish album-style MP3 playlists directly on WordPress.
It is intentionally lightweight: no external frontend libraries, no bloated builders, and no paid add-on dependency for core playback/download workflows.
It keeps the setup simple and fast while offering a feature combination that is often split across paid tiers in other plugins.

Features include:
- Album custom post type
- Shortcode embed: [valacuhi_mp3_player id="123"]
- Play/Pause, Previous/Next, seek bar
- Mute/Unmute and Mix mode
- MP3 metadata extraction (title, artist, album, genre, duration)
- Embedded artwork extraction from MP3 files
- Per-track and album ZIP download buttons with counters
- Premium lightweight v0.4 interface
- v0.4.3 unified inline SVG control icon family
- v0.4.4 mobile control-row polish and clearer Mix active state

== Installation ==
1. Upload the plugin files to the `/wp-content/plugins/valacuhi-mp3-player` directory, or install via WordPress Plugins screen.
2. Activate the plugin through the `Plugins` screen in WordPress.
3. Go to `Albums` and create a new album.
4. Set featured image (album art fallback).
5. Add MP3 files in `Album Tracks` metabox.
6. (Optional) Add Album ZIP URL.
7. Publish album.
8. Find the album ID:
   - Open `Albums -> All Albums`.
   - Hover the album title or click `Edit`.
   - In the browser URL, find `post=123` or `post.php?post=123`.
   - Use that number in the shortcode.
9. Use shortcode `[valacuhi_mp3_player id="YOUR_ALBUM_ID"]` on any page/post.

== Frequently Asked Questions ==
= What Users Can Do in the Player? =
- Select any track from the list
- Play/Pause
- Previous/Next track
- Seek through progress bar
- Mute/Unmute
- Toggle Mix mode
- Download individual tracks
- Download entire album ZIP (if configured)

= Why are style changes not visible after update? =
- F12, then right click on Reload button and choose "Empty cache and hard reload".
- Plugin version updates append `?ver=0.4.6` to CSS/JS for cache busting.

= What about Metadata Behavior? =
- Title: MP3 `title` tag, fallback to filename
- Artist/Album/Genre: shown only when tag exists
- Duration: extracted from MP3 metadata
- Artwork: embedded MP3 image preferred; album featured image used as fallback

= Why is metadata missing for some tracks? =
Metadata is read from MP3 tags. If tags are missing in the file, those fields stay empty.

= Why does artwork not appear? =
Artwork is extracted from embedded MP3 image frames. If an MP3 has no embedded image, the album featured image is used.

= Are download counters permanent analytics? =
No. Counters use lightweight transients and are intended as simple UI feedback.

== Changelog ==
= 0.4.6 =
* Prefixed CPT identifier from `album` to `valacuhi_album` for directory compatibility
* Added one-time migration of legacy `album` posts to the new prefixed CPT
* Prefixed transient keys and AJAX action names to avoid cross-plugin collisions
* Reworked media URL-to-path resolution to use robust WordPress APIs
* Hardened track URLs POST handling for stricter validation/sanitization flow

= 0.4.5 =
* Switched audio metadata/artwork parsing to WordPress core APIs
* Plugin Check remediation pass for submission readiness
* Packaging cleanup for WordPress.org review

= 0.4.4 =
* Mobile-only control-row polish for small screens
* Centered Album CTA when it wraps to second row
* Stronger Mix on/off visual state clarity

= 0.4.3 =
* Unified inline SVG icon family for controls (prev/play-pause/next/mix/volume/download)
* Kept Play/Pause visually larger while secondary controls remain equal-sized
* Improved consistent icon rendering across environments

= 0.4 =
* Premium lightweight UI refresh (Frosted Light style)
* Improved visual hierarchy, controls, and track list styling
* WordPress.org hardening improvements

= 0.3.1 =
* Added genre extraction and display
* Added mute/unmute and mix controls
* Title fallback from MP3 title to filename

= 0.3 =
* Playback reliability improvements
* Embedded artwork shown in player and list
* Metadata extraction and progress UX improvements

== Upgrade Notice ==
= 0.4.6 =
*WordPress.org review-response update: prefixed identifiers, migration-safe CPT update, and stricter path/input hardening.

== Notes for Site Owners==
- Download counters are transient-based lightweight counters.
- They are useful for UI feedback, not long-term analytics.
                                            
