MetaWave lets independent artists & collectors upload MP3s, embed / replace cover art, batch update artwork, organize tracks into drag‑sortable albums, manage rich metadata, collaborate with others, and share public profiles – all in a sleek, fast, theme‑aware UI.

MetaWave - “A lightweight self‑hosted mini streaming console + collaborative curator workspace” built on an audibly opinionated stack. ⚡

1. About MetaWave
2. Core Features
3. Albums & Drag Architecture
4. Track Metadata & Artwork Pipeline
5. Tech Stack
6. UI / UX Highlights
7. User Interface
8. Data Model
   • Tables
   • Schema
9. Getting Started
10. Environment Variables
11. Development Scripts
12. Batch Artwork Updating
13. Accessibility & Theming
14. Performance Techniques
15. Security & Validation
16. AWS Deployment
    • GitHub Actions
    • Ansible & Terraform
17. Docker & Containerization
    • DevContainer
18. Testing & Quality Assurance
19. Makefile & Shell Scripts
20. Contributing
21. License
22. Author

MetaWave is a self‑managed music library & micro‑publishing interface for indie creators:

Use it to curate demos, bundle thematic EP drops, share works-in-progress with friends, or just tame the chaos of personal recordings.

MetaWave is LIVE! You can try it out at metawave.vercel.app. Feel free to create an account, upload some tracks, and explore the features! 🚀

MetaWave is designed to be a fast, responsive, and intuitive music library management tool with the following core features:

MetaWave's track management is designed to be intuitive and efficient, allowing users to easily manage their audio files and associated metadata. The process involves several key steps:

MetaWave is built on a modern, robust stack that leverages the latest technologies to provide a seamless user experience. Here’s a breakdown of the key components:

MetaWave's UI is designed to be fast, responsive, and intuitive, with a focus on user experience. Here are some key highlights:

• Animated Landing Hero: Gradient backgrounds, typing / rotating text (planned), CTA emphasis.
• Hero Album Section: Contrast-preserving overlay with dynamic gradient fallback if no cover.
• Card Micro‑Interactions: Hover borders, shadow elevation, icon actions fade-in (opacity group revealing).
• Input Styling: Soft focus shadows + accessible ring for clarity.
• Drag & Drop: Smooth reordering with dnd-kit, immediate UI feedback on reorder (only available on album detail).
• Adaptive Waveforms: Theme toggle triggers waveform recolor; fallback placeholder while loading.
• Grid Strategy: Strict max of 4 columns large; preserves card width legibility.
• Progress-less Upload: Lean immediate preview with object URL pre-insert for covers & avatars.
• Skeleton Consistency: Uniform radii + brand tinted neutral backgrounds for perceived speed.
• Accessible Labels: Every dialog field labeled (name, handle, dates, etc.).

MetaWave aims to provide a polished, cohesive experience that feels both modern and familiar, with a focus on usability and accessibility.

MetaWave's data model is designed to be simple yet effective, focusing on user profiles, tracks, albums, and their relationships. The current version includes the following tables:

For more details on the schema, refer to the database directory, where you can find the SQL migration files and schema definitions.

To get started with MetaWave, follow these steps:

git clone https://github.com/hoangsonww/MetaWave-MP3-App.git
cd MetaWave-MP3-App

# Install
npm install

# Copy env
cp .env.local.example .env.local
# Fill with: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY

# Dev
npm run dev
# http://localhost:3000

If using Supabase locally:

supabase start
# Add SQL schema (profiles, tracks, albums, album_tracks)

MetaWave requires several environment variables to function correctly. Create a .env.local file in the root directory and populate it with the following variables:

MetaWave includes several npm scripts to streamline development and deployment:

Feel free to add more scripts as needed, such as for database migrations or custom build steps.

We've implemented a Batch Cover Dialog to streamline the process of updating cover art for multiple tracks at once. This feature is designed to enhance user experience by allowing quick updates without needing to edit each track individually.

1. Select tracks (checkbox overlay on library grid)
2. Open Batch Cover Dialog
3. Upload single image → stored once per track path (ensures unique paths, optional dedupe later)
4. Update each track row cover_art_url sequentially (could be parallel batched in future)
5. Success toast + local reload

Future enhancements:

• Parallel Promise.allSettled
• MD5 hashing to avoid duplicate uploads

MetaWave is built with accessibility and theming in mind, ensuring a consistent and inclusive user experience across different devices and preferences. Here are some key aspects:

MetaWave employs several performance techniques to ensure a smooth user experience, especially when dealing with large libraries and media files. Here are some key strategies:

MetaWave takes security and data integrity seriously, implementing several layers of validation and access control:

We also provide an optional AWS deployment setup for those who prefer a more robust infrastructure. This includes:

• Ansible for provisioning and configuration management.
• Terraform for infrastructure as code, allowing you to define your AWS resources declaratively.
• Docker for containerization, ensuring consistent environments across development and production.
• Nginx as a reverse proxy for serving the Next.js application and handling static assets.
• GitHub Actions for CI/CD, automating the build and deployment process.

For detailed instructions on setting up the AWS deployment, refer to the AWS Deployment Guide.

MetaWave uses GitHub Actions for continuous integration and deployment. The workflow includes:

• Running tests on every push and pull request.
• Building the application for production.
• Deploying to Vercel or AWS based on the branch.
• Linting and formatting checks to ensure code quality.
• Generating documentation and updating the README with the latest changes.
• Sending notifications on build success or failure to the team.
• Caching dependencies to speed up build times.
• Using environment variables for sensitive information like API keys and database URLs.
• and more...

MetaWave uses Ansible and Terraform to automate the deployment process on AWS. This allows for easy provisioning of resources, configuration management, and infrastructure as code.

Ansible is used for:

• Setting up the server environment (e.g., installing dependencies, configuring Nginx).
• Deploying the application code to the server.
• Managing server configurations and updates.
• Running database migrations and other setup tasks.
• Automating routine maintenance tasks.
• Configuring security groups, firewalls, and other network settings.
• Setting up monitoring and logging services.
• Managing SSL certificates for secure HTTPS connections.
• and more...

Terraform is used for:

• Defining and provisioning AWS resources (e.g., EC2 instances, RDS databases, S3 buckets).
• Managing infrastructure as code, allowing for version control and reproducibility.
• Creating reusable modules for common infrastructure patterns.
• Managing dependencies between resources, ensuring they are created in the correct order.
• Handling resource updates and rollbacks in a controlled manner.
• Integrating with other tools and services in the AWS ecosystem.
• Managing state files to track the current state of the infrastructure.

With Ansible and Terraform, you can easily deploy MetaWave to AWS with a few commands, ensuring a consistent and reliable deployment process.

MetaWave can be easily containerized using Docker, allowing for consistent development and production environments. The Docker setup includes:

• A Dockerfile for building the application image.
• A docker-compose.yml file for orchestrating the application, database, and any other services.
• Environment variables for configuration, similar to the .env.local file used in development.
• Volume mounts for persistent storage of uploaded files and database data.
• Health checks to ensure the application is running correctly.

To run MetaWave in a Docker container, follow these steps:

# Build the Docker image
docker build -t metawave .

# Run the container
docker run -d -p 3000:3000 --env-file .env.local metawave
# Access the application at http://localhost:3000

To run MetaWave with Docker Compose, use the provided docker-compose.yml file:

# Start the application with Docker Compose
docker-compose up -d
# Access the application at http://localhost:3000

Feel free to customize the Docker setup to fit your deployment needs, such as adding additional services or modifying environment variables.

For a seamless development experience, MetaWave also supports DevContainers. This allows you to run the application in a containerized environment with all dependencies pre-configured. To use the DevContainer setup:

1. Ensure you have Visual Studio Code and the Remote - Containers extension installed.
2. Open the project in VS Code.
3. When prompted, select "Reopen in Container" to start the development environment.
4. Once the container is running, you can use the integrated terminal to run development commands like npm run dev.
5. You can also use the VS Code debugger to set breakpoints and debug the application directly within the container.
6. The DevContainer setup includes all necessary tools and configurations, such as Oh My Zsh, Node.js, npm, and the required environment variables, to ensure a smooth development experience.

MetaWave includes a comprehensive testing suite to ensure code quality and functionality. The testing setup consists of:

• Unit Tests: Written using Jest, covering core functionality such as track metadata handling, album management, and user profile operations.
• End-to-End Tests: Planned using Playwright to simulate user interactions and verify the overall application flow.
• Continuous Integration: GitHub Actions configured to run tests on every pull request, ensuring that new changes do not break existing functionality.
• Code Quality: ESLint and Prettier are used to enforce coding standards and maintain consistent code style across the project.
• Test Coverage: Code coverage reports generated by Jest to identify untested parts of the codebase and ensure comprehensive test coverage.
• Mocking: Use of mocking libraries to simulate external dependencies, such as Supabase, during tests to isolate functionality and ensure reliable test results.
• Snapshot Testing: Jest snapshot tests for components to catch unexpected changes in the UI.
• Accessibility Testing: Accessibility testing tools to ensure compliance with WCAG standards and provide an inclusive user experience.
• Performance Testing: Performance tests to measure response times and resource usage under various load conditions.

To run the tests, use the following command:

cd web
npm run test

# or run in watch mode for continuous testing during development
npm run test:watch

# or generate a coverage report
npm run test:coverage

MetaWave includes a Makefile and several shell scripts to simplify common development tasks and automate workflows. The Makefile provides a convenient way to run commands without needing to remember complex npm scripts. Here are some key features:

• Makefile Commands: Define common tasks such as make dev, make build, make lint, and make format to streamline development workflows.
• Shell Scripts: Custom shell scripts for tasks like database migrations, environment setup, and deployment automation.
• Environment Setup: Scripts to initialize the development environment, including installing dependencies and setting up local configurations.
• Database Migrations: Use shell scripts to apply database migrations and ensure the schema is up-to-date.
• Deployment Automation: Scripts to automate the deployment process, including building the application, pushing changes to the server, and restarting services.
• Custom Commands: Add custom commands to the Makefile for specific tasks, such as running tests, generating documentation, or cleaning up temporary files.
• Cross-Platform Compatibility: Ensure that the scripts work on both Unix-like systems (Linux, macOS) and Windows, using tools like cross-env for environment variable management.
• Documentation: Include comments in the Makefile and shell scripts to explain each command and its purpose, making it easier for contributors to understand and use.

Example Makefile commands:

# Start the development server
make dev

# Build the production version of the application
make build

# Build Docker image
make docker-build

# Push Docker image to AWS ECR
make docker-push

# Deploy the application
make deploy

# etc.

Contributions are welcome! If you have ideas for improvements, bug fixes, or new features, please follow these guidelines:

1. Fork the repository and create your branch from master.
2. Make your changes and ensure they pass existing tests.
3. Commit your changes with a clear message following the Conventional Commits format. Be sure to run npm run format to ensure code style consistency.
4. Push to your fork and submit a pull request.
5. Describe your changes in the pull request description, including any relevant context or screenshots.
6. Link issues: If your PR addresses an issue, reference it in the description (e.g., "Fixes #123").
7. Follow the code style: Use Prettier for formatting and ESLint for linting. Ensure your code adheres to the project's coding standards.
8. Test your changes: If you add new features or fix bugs, please include tests to cover your changes.
9. Be respectful: Maintain a positive and constructive tone in discussions and code reviews.
10. Review process: Your PR will be reviewed by the maintainers. They may request changes or provide feedback before merging.

For bugs: please include steps, expected, actual, and any console errors - this helps us reproduce and fix issues quickly.

MIT License – See LICENSE.

Built with late‑night loops + waveforms by Son Nguyen in 2025.

• GitHub: @hoangsonww
• LinkedIn: linkedin.com/in/hoangsonw
• Site: sonnguyenhoang.com
• Email: hoangson091104@gmail.com

“Curate. Polish. Share. Repeat.” 🎚️

Enjoy sculpting your catalog with MetaWave. Your music, beautifully organized. 🎧

🔝 Back to Top