EchoVault Music Uploader

A secure, self-service audio upload and instant playback system for WordPress. Visitors drop an audio file into a form, an administrator approves it in one click, and it plays instantly through an embedded HTML5 player — no page rebuild, no external streaming service.

Built as a standalone plugin (works with any theme) plus an optional lightweight companion theme with brand colours and a ready-made front page.

Features

• 🎧 Drag-and-drop upload form — [echovault_upload_form] shortcode, with client-side validation and no page reload.
• ▶️ Automatic audio player — [echovault_player id="123"] for a single track, [echovault_recent_tracks] for a feed of the latest approved ones.
• 🛡️ Moderation by default — every upload waits for admin approval before it goes live (can be turned off in Settings).
• 🔒 Defence in depth — real MIME-type sniffing (not just file extension checks), per-IP rate limiting, nonce-protected REST endpoint, and a hardened upload folder that blocks direct PHP execution.
• 📊 Storage dashboard — see how much space uploads are using, with a configurable warning threshold.
• 🎨 Brand-ready styling — colours, fonts and logo placement exposed as simple CSS variables / theme support, no page-builder required.
• 🧩 Built for extension — tracks live in their own custom post type, so playlists, e-commerce add-ons (WooCommerce), or user-account ownership can be layered on top later without a rewrite.

Project structure

echovault-wp/
├── .github/workflows/ci.yml        # GitHub Actions: PHPCS + PHPUnit + Codecov
├── assets/
│   ├── css/                        # frontend.css (brand vars, player, upload form) + admin.css
│   ├── images/logo-placeholder.svg # swap for your real logo
│   └── js/frontend-upload.js       # drag & drop + fetch()-based REST upload
├── docs/
│   ├── HANDOFF.md                  # plugin list, custom code map, demo script
│   ├── SERVER-REQUIREMENTS.md      # PHP/webserver tuning for large audio files
│   └── USER-ACCOUNTS-MIGRATION.md  # accounts vs. anonymous uploads, pros/cons + migration steps
├── includes/
│   ├── class-echovault-admin.php       # moderation screen + settings page
│   ├── class-echovault-player.php      # [echovault_player], [echovault_recent_tracks]
│   ├── class-echovault-plugin.php      # bootstraps every component
│   ├── class-echovault-post-type.php   # the "echovault_track" CPT
│   ├── class-echovault-rest-api.php    # POST /wp-json/echovault/v1/upload
│   ├── class-echovault-security.php    # MIME validation, rate limiting, folder hardening
│   ├── class-echovault-settings.php    # Settings API wrapper
│   ├── class-echovault-storage.php     # upload paths + human-readable usage stats
│   └── class-echovault-uploader.php    # [echovault_upload_form] + upload processing
├── templates/                      # small PHP view partials used by the classes above
├── tests/                          # PHPUnit + WP_Mock unit tests
├── theme/echovault-theme/          # optional child theme (Twenty Twenty-One parent)
├── composer.json
├── phpcs.xml.dist                  # WordPress Coding Standards ruleset
├── phpunit.xml.dist
├── uninstall.php
├── LICENSE                         # MIT
└── README.md

Requirements

• WordPress 6.0+
• PHP 7.4+
• A host that allows setting upload_max_filesize / post_max_size above the default (see docs/SERVER-REQUIREMENTS.md for exact values and why)

Quick start

git clone https://github.com/MrBoyard7/echovault-wp.git
cd echovault-wp
composer install

Then, on a local WordPress install:

1. Copy (or symlink) the echovault-wp folder into wp-content/plugins/.
2. Activate EchoVault Music Uploader from the Plugins screen.
3. (Optional) Copy theme/echovault-theme into wp-content/themes/ and activate it — it requires the Twenty Twenty-One theme to also be installed, since it's a child theme.
4. Create a page containing [echovault_upload_form] and set it as your homepage, or drop the shortcode into any existing page/post.

Usage

Admin screens live under EchoVault in the WordPress sidebar:

• Tracks — approve, reject, or delete submissions.
• Settings — max upload size, storage warning threshold, and whether approval is required at all.

User accounts: yes or no?

The plugin works fully without visitor accounts — moderation is what keeps content clean, not registration. If you later want per-user dashboards, ownership, or a foundation for e-commerce add-ons, see docs/USER-ACCOUNTS-MIGRATION.md for the trade-offs and the exact steps to add it — it's additive, not a rewrite.

Testing

This repository ships two layers of testing:

composer install
composer run cs     # WordPress Coding Standards (PHPCS)
composer run test   # PHPUnit + WP_Mock unit tests

Every push and pull request runs the same two commands, on PHP 7.4 through 8.3, via GitHub Actions (see the CI badge above); coverage is reported to Codecov automatically.

If you just want a quick sanity check without installing Composer dependencies, verify every file's PHP syntax:

find . -name "*.php" -not -path "./vendor/*" -exec php -l {} \;

Roadmap

• [ ] Optional user accounts + "My Tracks" dashboard (see migration doc above)
• [ ] Playlist creation
• [ ] WooCommerce integration for paid downloads / premium tracks
• [ ] Waveform preview instead of a plain progress bar

Contributing

See CONTRIBUTING.md.

License

Released under the MIT License.

Copyright (c) 2026 Prince Boyard MBOUNGOU NGOMA

Author

Prince Boyard MBOUNGOU NGOMA GitHub: @MrBoyard7