Skip to content

Commit 5149f19

Browse files
FelixNgFenderFelixNgFender
committed
docs: readme and buncha otha stuff
1 parent df5b511 commit 5149f19

File tree

5 files changed

+260
-23
lines changed

5 files changed

+260
-23
lines changed

‎.env.example

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# General
2+
# Manually handle Node.js signals for graceful shutdowns and uncaught exceptions
3+
NEXT_MANUAL_SIG_HANDLE=true
4+
# Next.js server parameters
5+
PROTOCOL=http
6+
HOST=localhost
7+
APP_PORT=3000
8+
9+
10+
# Authentication
11+
AUTH_COOKIE_DURATION_S=86400
12+
# Google OAuth client ID
13+
GOOGLE_CLIENT_ID=
14+
# Google OAuth client secret
15+
GOOGLE_CLIENT_SECRET=
16+
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/sign-in/google/callback
17+
# GitHub OAuth client ID
18+
GITHUB_CLIENT_ID=
19+
# GitHub OAuth client secret
20+
GITHUB_CLIENT_SECRET=
21+
22+
23+
# Logging
24+
APP_LOGGING=true
25+
# Possible values are detailed in `src/config/env.ts`
26+
LOG_LEVEL=debug
27+
28+
29+
# Rate limiting
30+
ENABLE_RATE_LIMIT=false
31+
32+
33+
# Captcha
34+
NEXT_PUBLIC_ENABLE_CAPTCHA=false
35+
NEXT_PUBLIC_CAPTCHA_SITE_KEY=
36+
CAPTCHA_SECRET_KEY=
37+
38+
39+
# Email
40+
ENABLE_EMAIL=false
41+
AWS_REGION=
42+
AWS_ACCESS_KEY_ID=
43+
AWS_SECRET_ACCESS_KEY=
44+
45+
46+
# Analytics
47+
ENABLE_ANALYTICS=false
48+
UMAMI_SCRIPT_URL=
49+
UMAMI_ANALYTICS_ID=
50+
51+
52+
# Database
53+
DATABASE_LOGGING=false
54+
DATABASE_URL=postgresql://postgres:[email protected]:5432/postgres
55+
REDIS_URL=redis://127.0.0.1:6379/0
56+
57+
58+
# S3
59+
S3_ENDPOINT=minio
60+
S3_PORT=9000
61+
S3_USE_SSL=false
62+
S3_ACCESS_KEY=minio
63+
S3_SECRET_KEY=miniosecret
64+
S3_BUCKET_NAME=mu2mi-assets
65+
S3_PRESIGNED_URL_EXPIRATION_S=900
66+
67+
68+
# Replicate
69+
# API token and webhook secret can be generated in the Replicate account settings
70+
REPLICATE_API_TOKEN=
71+
REPLICATE_WEBHOOK_SECRET=
72+
MUSIC_GENERATION_MODEL_VERSION=b05b1dff1d8c6dc63d14b0cdb42135378dcb87f6373b0d3d341ede46e59e2b38
73+
STYLE_REMIX_MODEL_VERSION=0b769f28e399c7c30e4f2360691b9b11c294183e9ab2fd9f3398127b556c86d7
74+
TRACK_SEPARATION_MODEL_VERSION=25a173108cff36ef9f80f854c162d01df9e6528be175794b81158fa03836d953
75+
TRACK_ANALYSIS_MODEL_VERSION=001b4137be6ac67bdc28cb5cffacf128b874f530258d033de23121e785cb7290
76+
MIDI_TRANSCRIPTION_MODEL_VERSION=a7cf33cf63fca9c71f2235332af5a9fdfb7d23c459a0dc429daa203ff8e80c78
77+
LYRICS_TRANSCRIPTION_MODEL_VERSION=3ab86df6c8f54c11309d4d1f930ac292bad43ace52d10c80d87eb258b3c9f79c

‎CONTRIBUTING.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Contributing to Mu2Mi
2+
3+
Mu2Mi welcomes contributions from the community. There are many ways to get involved!
4+
5+
## Provide Feedback
6+
7+
You might find things that can be improved while you are using Mu2Mi. You can help by [submitting an issue](https://github.com/FelixNgFender/Mu2Mi/issues/new) when:
8+
9+
- Mu2Mi crashes, or you encounter a bug that can only be resolved by refreshing the browser.
10+
- An error occurs that is unrecoverable, causes data integrity problems or loss, or generally prevents you from using Mu2Mi.
11+
- A new feature or an enhancement to an existing feature will improve the utility or usability of Mu2Mi.
12+
13+
Before creating a new issue, please confirm that an existing issue doesn't already exist.
14+
15+
## Participate in the Community
16+
17+
You can engage with the community by:
18+
19+
- Helping other users on [Discord](https://discord.gg/7BkTD7RNRG).
20+
- Improving documentation
21+
- Participating in general discussions about open source, music, and AI
22+
- Authoring new Mu2Mi features
23+
24+
## Contributing Code
25+
26+
You can contribute to Mu2Mi by:
27+
28+
- Enhancing current functionality
29+
- Fixing bugs
30+
- Adding new features and capabilities
31+
32+
Before starting your contribution, especially for core features, I encourage you to reach out to me on [Discord](https://discord.gg/7BkTD7RNRG). This allows me to ensure that your proposed feature aligns with the project's roadmap and goals. Developers are the key to making Mu2Mi the best tool it can be, and I value input from the community.
33+
34+
I look forward to working with you to improve Mu2Mi.
35+
36+
### Steps to Contribute Code
37+
38+
Follow the following steps to ensure your contribution goes smoothly.
39+
40+
1. Fork the repository to your GitHub account.
41+
2. Clone the forked repository to your local machine.
42+
3. Create a new branch for your feature or bug fix.
43+
4. Commit your changes to your branch.
44+
5. Push your changes to your fork on GitHub.
45+
6. Create a pull request to the main repository.
46+
7. Wait for the maintainers to review your pull request.
47+
8. Make any necessary changes to your pull request.
48+
9. Once your pull request is approved, it will be merged into the main repository.
49+
10. Celebrate your contribution to Mu2Mi!
50+
51+
### Development Environment
52+
53+
#### Prerequisites
54+
55+
- Node.js v21.6.1
56+
- Docker
57+
- Docker Compose
58+
59+
#### Setting Up Your Development Environment
60+
61+
Mu2Mi is built with Next.js, PostgreSQL, Minio, and Redis. The development environment is orchestrated with Docker Compose. To set up your development environment:
62+
63+
1. Have the required dependencies installed on your machine and the repository cloned.
64+
2. Create a `.env` file in the root directory of the project. Use the `.env.example` file as a template and fill out the values required. The `.env.example` file has some default values that you can use. Rate limiting, captcha, email, and analytics are disabled by default in development. You can view the [environment variable schema](src/config/env.ts) to see which are required for booting up the Next.js server.
65+
66+
```bash
67+
cp .env.example .env
68+
```
69+
70+
3. Run `make up` to start the development environment. *Quick tip: The `Makefile` and `compose.yaml` files are used to manage the development environment and contain other useful commands*.
71+
4. Run `npm i` to install the project dependencies.
72+
5. Run `npm run dev` to start the development server.
73+
6. Visit `http://localhost:3000` in your browser to view the application.
74+
7. Run `make down` to stop the development environment.
75+
8. (Optional) Run `make clean` to remove all persistent Docker volumes and images.
76+
77+
#### Testing Track Processing Functionality
78+
79+
To test out track processing functionality that uses Replicate service, you will need to have Replicate API token and webhook secret, which can be generated in your Replicate account settings, configured as environment variables in your `.env` file. And you will also need to set up tunnels using either [ngrok](https://ngrok.com/) or [localtunnel](https://localtunnel.github.io/www/). The two tunnels needed should be set up for the following ports:
80+
81+
- 3000 (Next.js)
82+
- 9000 (Minio)
83+
84+
Once the tunnels are set up, update these variables in your `.env`:
85+
86+
- `PROTOCOL` to `https`
87+
- `HOST` to the Next.js tunnel URL
88+
- `APP_PORT` to `443` for `https` connection
89+
- `S3_ENDPOINT` to the Minio tunnel URL
90+
- `S3_PORT` to `443` for `https` connection
91+
- `S3_USE_SSL` to `true` for `https` connection
92+
93+
You may also need to restart the Next.js server to apply the changes.
94+
95+
### Codebase Overview
96+
97+
#### Data Access Layer
98+
99+
Exported functions in the `src/models` directory are ready to be consumed in Route Handlers, Server Actions, and Server Components. They act as a data access layer and interact with the database.
100+
101+
#### Data Fetching and Mutation
102+
103+
Server Components get their data from queries in `queries.ts` files, re-export queries from `actions.ts` to get them inside the `'use server'` boundary, which enables the use of `useQuery` and `useMutation` hooks in Client Components. Route Handlers should be wrapped with `withErrorHandling` in [the error module](src/lib/error.ts) to handle errors.
104+
105+
Server Actions in `actions.ts` files. Server Actions should be wrapped with either `action` or `authAction` in [the safe-action module](src/lib/safe-action.ts) to handle errors and add the current user and session to the context.

‎README.md

+73-23
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,86 @@
1-
This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
1+
<div align="center">
2+
<picture>
3+
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/FelixNgFender/Mu2Mi/raw/main/src/app/opengraph-image.png">
4+
<img alt="Mu2Mi logo" src="https://github.com/FelixNgFender/Mu2Mi/raw/main/src/app/opengraph-image.png" width="100%">
5+
</picture>
6+
</div>
27

3-
## Getting Started
8+
<br><br>
49

5-
First, run the development server:
10+
<div align="center">
611

7-
```bash
8-
npm run dev
9-
# or
10-
yarn dev
11-
# or
12-
pnpm dev
13-
# or
14-
bun dev
15-
```
12+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
13+
[![Issues - Mu2Mi](https://img.shields.io/github/issues/FelixNgFender/Mu2Mi)](https://github.com/FelixNgFender/Mu2Mi/issues)
14+
![GitHub Release](https://img.shields.io/github/v/release/FelixNgFender/Mu2Mi)
1615

17-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
16+
![Lint](https://github.com/FelixNgFender/Mu2Mi/actions/workflows/lint.yml/badge.svg)
1817

19-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
18+
</div>
2019

21-
This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
20+
<h1 align="center">The Open Source AI Musical Toolkit</h1>
21+
<div align="center">
22+
Mu2Mi is an open source, AI-powered toolkit for all your musical needs. Remove vocals, isolate instruments, transcribe lyrics and instruments, generate and remix songs.
23+
</div>
24+
</br>
2225

23-
## Learn More
26+
<p align="center">
27+
<a href="https://github.com/FelixNgFender/Mu2Mi/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%F0%9F%90%9B+Bug+Report%3A+">Report Bug</a>
28+
·
29+
<a href="https://github.com/FelixNgFender/mu2mi/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%F0%9F%9A%80+Feature%3A+">Request Feature</a>
30+
·
31+
<a href="https://discord.gg/7BkTD7RNRG">Join Our Discord</a>
32+
·
33+
<a href="https://twitter.com/felixcantcode">Twitter</a>
34+
</p>
2435

25-
To learn more about Next.js, take a look at the following resources:
36+
<!-- TODO: Replace with GIF demo -->
37+
<div align="center"><img src="https://github.com/FelixNgFender/Mu2Mi/raw/main/demo.png" width="80%" ></div>
2638

27-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
28-
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
39+
## Features
2940

30-
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
41+
- **Music Generation**: Craft unique compositions from text or melodies.
42+
- **Style Remix**: Remix and reimagine a track in various music styles.
43+
- **Track Separation**: Isolate vocals and instruments within a track.
44+
- **Track Analysis**: Analyze the tempo, key, and structure of a musical piece.
45+
- **MIDI Transcription** : Convert audio to MIDI data.
46+
- **Lyrics Transcription**: Transcribe lyrics of any language from audio recordings into text and translate lyrics of any language to English.
47+
- **Audio Preview**: Preview audio files in the browser.
48+
- **MIDI Preview**: Preview MIDI files in the browser.
49+
- **Track Download**: Download processed tracks in a zip.
50+
- **Track Sharing**: Share tracks with others through a public link.
3151

32-
## Deploy on Vercel
52+
## Contributing
3353

34-
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
54+
Navigate to the [contributing guide](CONTRIBUTING.md) to get started.
3555

36-
Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
56+
## Self-Hosting
57+
58+
To self-host Mu2Mi, follow the instructions in the [self-hosting guide](SELF_HOSTING.md).
59+
60+
## Credits
61+
62+
Major thanks to the following open-source projects for making this possible:
63+
64+
- [Next.js](https://github.com/vercel/next.js)
65+
- [MusicGen](https://github.com/facebookresearch/audiocraft/blob/main/docs/MUSICGEN.md)
66+
- [BTC](https://github.com/jayg996/BTC-ISMIR19)
67+
- [Demucs](https://github.com/facebookresearch/demucs)
68+
- [All-In-One Music Structure Analyzer](https://github.com/mir-aidj/all-in-one#all-in-one-music-structure-analyzer)
69+
- [PyTSMod](https://github.com/KAIST-MACLab/PyTSMod)
70+
- [Basic Pitch](https://github.com/spotify/basic-pitch)
71+
- [Whisper](https://github.com/openai/whisper)
72+
- [Waveform Playlist](https://github.com/naomiaro/waveform-playlist)
73+
- [magenta-js](https://github.com/magenta/magenta-js/tree/master/music)
74+
75+
## License
76+
77+
This repository contains Mu2Mi, covered under the [MIT License](LICENSE), except where noted.
78+
79+
## Code of Conduct
80+
81+
This project has adapted the Code of Conduct from the [Contributor Covenant](https://www.contributor-covenant.org/). For more information see the [Code of Conduct](CODE_OF_CONDUCT.md) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
82+
83+
## Questions
84+
85+
For more information on how to use, develop, and self-host Mu2Mi, join our community on
86+
[Discord](https://discord.gg/7BkTD7RNRG).

‎SELF_HOSTING.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Self-Hosting Mu2Mi
2+
3+
Full self-hosting capability is on the roadmap for Mu2Mi. The only online dependency left are the AI models currently served by [Replicate](https://replicate.com).
4+
5+
In the meantime, you can run Mu2Mi locally for development purposes. To do so, follow the steps detailed in the [Development Environment](CONTRIBUTING.md#development-environment) section of the contributing guide.

‎demo.png

513 KB
Loading

0 commit comments

Comments
 (0)