MSW Open Music Project

Introduction

A light weight personal music streaming platform.

[toc]

How to build

Build the back-end server

make linux or make windows

The executable file is named msw-open-music or msw-open-music.exe

Build the font-end web pages

To build production web page make web

This command will go into web directory and install node_modules. Then execute npm run build command. The built web pages is under web/build directory.

To start the development, run cd web and npm start

Usage

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

By default:

• URL matched /api/* will process by back-end server.
• Others URL matched /* will be served files under web/build/

Run back-end server

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.

config.json description

• database_name string type. The filename of sqlite3 database. Will create if that file doesn't exist.
• addr string type. The listen address and port.
• token string type. Password.
• ffmpeg_config_list list type, include ffmpegConfig object.
• file_life_time integer type (second). Life time for temporary file. If the temporary file is not accessed for more than this time, back-end server will delete this file.
• cleaner_internal integer type (second). Interval for tmpfs checking temporary file.
• root string type. Directory to store temporary files. Default is /tmp, please modify this directory if you are using Windows.

Run font-end web page

Open your web browser to http://127.0.0.1:8080 you will see the web pages.

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.

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.

Change log

• 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).

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.

{
    "status": "OK"
}

Anonymous API

Anonymous API can be called by anonymous.

• /api/v1/hello Just for test purpose.

• /api/v1/get_file Get a file with stream mode.

  • Request example

    {
        "id": 123
    }
    

• /api/v1/get_file_direct Get a file with standart http methods, implement by http.ServeFile method.

  • Request example

    /api/v1/get_file_direct?id=30

• /api/v1/search_files Search files by filename.

  • Request example

    {
        "filename": "miku",
        "limit": 10,
        "offset" 0
    }
    

    Search all files' 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

    {
        "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
            }
        ]
    }
    

    id Identification of file.

    folder_id Identification of folder.

    foldername Folder name where the file in.

    filename File name.

    filesize File size, unit is byte.

• /api/v1/search_folders Search folders.

  • Request example.

    {
        "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

    {
        "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.

    {
        "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

    {
        "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

    {
        "feedback": "some suggestions..."
    }
    

  • Respond OK.

• /api/v1/get_file_info Get information of a specify file.

  • Request example.

    {
        "ID": 123
    }
    

  • Respond example.

    {
        "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

    {
        "id": 123,
        "config_name": "OPUS 128k"
    }
    

  • Respond example

    {
        "filesize": 1973241
    }
    

API needs token

• /api/v1/walk Walk directory, add all files and folders to database.

  • Request example

    {
        "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

    {
        "token": "your token"
    }
    

  • Respond OK

• /api/v1/add_ffmpeg_config Add ffmpeg config.

  Will be changed in future.

  • Request example

    {
        "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.

• /#/share/39

  Share a specific file.

• /#/search-folders/2614

  Show files in a specific folder.