heimoshuiyu/msw-open-music
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Update: README.md for dbms

Browse Source
This commit is contained in:
黑墨水鱼
2022-01-03 10:55:39 +08:00
parent 82da1aa48b
commit b295707a05
2 changed files with 77 additions and 278 deletions
Download Patch File Download Diff File Expand all files Collapse all files

355
README.md
View File

@@ -1,15 +1,47 @@
# MSW Open Music Project
## Introduction
A light weight personal music streaming platform.
## Introduction
![demo1](demo1.jpg)
[toc]
[TOC]
### What it can do
- Traverse the specified folder and index files whose extensions meet the requirements.
- Listening network port. Return to the front-end web page and process API requests.
- Call ffmpeg to transcode music or video.
- Manage files' information in the database, including adding tags, comments, etc.
### What it won't do
- Modify your file.
- Read music metadata (for example, composer, album, genre).
- Detect file changes (Need to manually update the database).
## ER Diagram
Entities Relationship Diagram
![ER Diagram](erdiagram.png)
- `avatar` entity may change in future rc version.
- The first time you run the program, the server will create an anonymous user with id 1. All users who are not logged in will be automatically logged in to this account.
- `tmpfs` is store in memory, which will be empty everytime server restart.
## How to build
Compile software from source code. If you use the pre-compiled version, you don’t need to do this.
### Build the back-end server
`make linux` or `make windows`
@@ -26,6 +58,12 @@ To start the development, run `cd web` and `npm start`
## Usage
> Security Warning (v1.2.0-rc1):
>
> The cookie stored in the client browser is encrypted using the environment variable "SESSION_KEY". The server will trust the client's cookie. Leaking this environment variable may cause security problems. This problem will be fixed in a future rc version.
>
> Password is not hashed in database, which will be fixed in next rc version.
Start back-end server. Server will listen on 8080 port.
Build the font-end web page, then go to <http://127.0.0.1:8080>
@@ -37,6 +75,8 @@ By default:
### Run back-end server
> Token authencation no longer support in v1.2.0 stable version.
Configuration file is `config.json`， **Please modify your `token`** 。
Default `ffmpeg_threads` is 1. Seems value larger than 1 will not increase the audio encode speed.
@@ -55,9 +95,15 @@ Default `ffmpeg_threads` is 1. Seems value larger than 1 will not increase the a
Open your web browser to <http://127.0.0.1:8080> you will see the web pages.
### Setup the first admin account
The first administrator account will be active automatically, other administrator accounts need active manually.
Go to register page, select the role to admin, and register the first admin account.
## About tmpfs
If the `Prepare` mode is enabled in the font-wed player, back-end server will convert the whole file into the temporary folder, then serve file using native method. This can avoid ffmpeg pipe break problem cause by unstable network connection while streaming audio.
If the `Prepare` mode is enabled in the font-wed player, back-end server will convert the whole file into the temporary folder, then serve file using native method. This cqan avoid ffmpeg pipe break problem cause by unstable network connection while streaming audio.
The default temporary folder is `/tmp`, which is a `tmpfs` file system in Linux operating system. Default life time for temporary files is 600 seconds (10 minutes). If the temporary file is not accessed for more than this time, back-end server will delete this file.
@@ -65,11 +111,10 @@ The default temporary folder is `/tmp`, which is a `tmpfs` file system in Linux
- `v1.0.0` First version. Ready to use in production environment.
- `v1.1.0` Use `React` to rewrite the font-end web pages (Previous using `Vue`).
- `v1.2.0` Add user, tag, review, video functions for DBMS course work.
## Back-end API references
API named `stream` means it transfer data using `io.Copy`, which **DO NOT** support continue getting a partially-downloaded audio.
API does not need to respond any data will return the following JSON object.
```json
@@ -78,296 +123,50 @@ API does not need to respond any data will return the following JSON object.
}
```
### Anonymous API
Sometime errors happen, server will return the following JSON object, which `error` is the detailed error message.
Anonymous API can be called by anonymous.
```json
{
"error": "Wrong password"
}
```
- `/api/v1/hello` Just for test purpose.
API does not need to send any data should use `GET` method, otherwise use `POST` method.
- `/api/v1/get_file` Get a file with `stream` mode.
Server use cookies to authencate a user. Any request without cookies will be consider from an anonymouse user.
- Request example
Some import source code file:
```json
{
"id": 123
}
```
- `pkg/api/api.go` define URL
- `/api/v1/get_file_direct` Get a file with standart `http` methods, implement by `http.ServeFile` method.
- `pkg/database/sql_stmt.go` define SQL queries and do the init job.
- Request example
- `pkg/database/struct.go` define JSON structures for database entities.
`/api/v1/get_file_direct?id=30`
## Font-end web pages
- `/api/v1/search_files` Search files by filename.
- `/#/` Get random files.
- Request example
- `/#/files` Search files.
```json
{
"filename": "miku",
"limit": 10,
"offset" 0
}
```
- `/#/files/39` Information of the which id is 39.
Search all files' name like `%miku%`. `%` is the wildcard in SQL. For example, `"filename": "miku%hatsune"` can match `hatsune miku`.
- `/#/files/39/review` Reviews of the file with file id 39.
`limit` Numbers of files in the respond. Should be within 1 - 10;
- `/#/files/39/share` Share page with the file id 39.
`offset` It is the offset of the result, related to the page turning function.
- `/#/folders` Search folders.
- Respond example
- `/#/folders/2614` Files in folder which id is 2614.
```json
{
"files": [
{
"id": 30,
"folder_id": 100,
"folder_name": "wonderful",
"filename": "memories.flac",
"filesize": 1048576
},
{
"id": 31,
"folder_id": 100,
"folder_name": "wonderful",
"filename": "memories (instrunment).flac",
"filesize": 1248531
}
]
}
```
- `/#/manage` Manage page.
`id` Identification of file.
- `/#/manage/users` List users.
`folder_id` Identification of folder.
- `/#/manage/users/1` Information of user whose id is 1.
`foldername` Folder name where the file in.
- `/#/manage/tags` List tags.
`filename` File name.
- `/#/manage/tags/1` Information of tag which id is 1.
`filesize` File size, unit is byte.
- `/api/v1/search_folders` Search folders.
- Request example.
```json
{
"foldername": "miku",
"limit": 10,
"offset": 0,
}
```
Search all folders' name like `%miku%`. `%` is the wildcard in SQL. For example, `"filename": "miku%hatsune"` can match `hatsune miku`.
`limit` Numbers of files in the respond. Should be within 1 - 10;
`offset` It is the offset of the result, related to the page turning function.
- Respond example
```json
{
"folders": [
{
"id": 100,
"foldername": "folder name"
},
{
"id": 101,
"foldername": "folder name (another)"
}
]
}
```
`id` Identification of folder.
`foldername` Folder name.
- `/api/v1/get_files_in_folder` Get files in a specify folder.
- Request example.
```json
{
"folder_id": 123,
"limit": 10,
"offset": 0
}
```
- Respond example.
Same with `/api/v1/search_files`
- `/api/v1/get_random_files` Randomly get 10 files.
- Request example.
GET `/api/v1/get_random_files`
- Respond example.
Same with `/api/v1/search_files`
- `/api/v1/get_file_stream`
Stream file with a ffmpeg config name.
- Request example.
GET `/api/v1/get_file_stream?id=123&config=OPUS%20128k`
- `/api/v1/get_ffmpeg_config_list`
Get ffmpeg config list
- Request example
GET `/api/v1/get_ffmpeg_config_list`
- Respond example
```json
{
"ffmpeg_config_list": [
{"name": "OPUS 256k", "args": "-c:a libopus -ab 256k"},
{"name": "WAV", "args": "-c:a wav"}
]
}
```
- `/api/v1/feedback` Send a feedback.
- Request example
```json
{
"feedback": "some suggestions..."
}
```
- Respond OK.
- `/api/v1/get_file_info` Get information of a specify file.
- Request example.
```json
{
"ID": 123
}
```
- Respond example.
```json
{
"id": 30,
"folder_id": 100,
"folder_name": "wonderful",
"filename": "memories.flac",
"filesize": 1048576
},
```
- `/api/v1/get_file_stream_direct` Get a ffmpeg converted file with native http method. This API support continue getting a partially-downloaded audio. Note, you should call `/api/v1/prepare_file_stream_direct` first and wait for its respond, then call this API.
- Request example
GET `/api/v1/get_file_stream_direct?id=123&config=OPUS%20128k`
- `/api/v1/prepare_file_stream_direct` Ask server to convert a file with specific ffmpeg config name. When the conver process is finished, server will reply with the converted file size.
- Request example
```json
{
"id": 123,
"config_name": "OPUS 128k"
}
```
- Respond example
```json
{
"filesize": 1973241
}
```
### API needs token
- `/api/v1/walk` Walk directory, add all files and folders to database.
- Request example
```json
{
"token": "your token",
"root": "/path/to/root",
"pattern": [".wav", ".flac"]
}
```
`token` The token in `config.json` file.
`root` Root directory server will walk throught
`pattern` A list of pattern that files ends with. Only files matched a pattern in list will be add to database.
- Respond OK
- `/api/v1/reset` Rest the **files and folders table**
- Request example
```json
{
"token": "your token"
}
```
- Respond OK
- `/api/v1/add_ffmpeg_config` Add ffmpeg config.
Will be changed in future.
- Request example
```json
{
"token": "your token",
"name": "OPUS",
"ffmpeg_config": {
"args": "-c:a libopus -ab 256k"
}
}
```
`name` Name of the ffmpeg config.
`ffmpeg_config`
`args`
- Respond OK
## Font-end API references
Currently only few APIs in font-end.
- `/#/files/39/share`
Share a specific file.
- `/#/folders/2614`
Show files in a specific folder.
- `/#/manage/feedbacks` List feedbacks.

BIN
erdiagram.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 93 KiB