MSW Open Music Project

简介

Fork from msw-file，目前是一个音乐播放器。

[toc]

编译 & 构建

编译后端

go build

如无任何输出，说明构建成功，可执行程序位于 msw-open-music

构建前端

make

说明：Makefile 脚本中的代码会在 dist 目录生成用于生产环境的前端 web 文件。这个脚本做的事情是简单地将 vue vue-router 等 js 文件替换成生产版本。并使用 minify 工具处理 css 和 html 文件。

使用

后端使用

初次使用请配置 config.json， 最重要的是配置 token 。

默认 ffmpeg 线程 ffmpeg_threads 为 1 ，大于 1 以上的值似乎对编码音频没有效果。

config.json 说明

• database_name 字符串类型，指定 sqlite3 单文件数据库的位置，如果不存在则会自动创建。
• addr api 服务监听端口，该参数会被传入 http.Serve.Addr
• token 字符串，作为管理密码
• ffmpeg_configs，字典，其键是 ffmpeg 配置的名称，其值是放入 ffmpeg -i input.mp3 -vn [此处] -f matroska - 的参数，类型是字符串。 注意： 前端会按键名来排序配置列表，并以列表中的第一项作为默认配置。
• file_life_time 临时文件生存时间，超过该时间没有访问该临时文件，tmpfs 将删除此文件。
• cleaner_internal 清理器的检查间隔。
• root 存放该临时文件目录， Windows 用户请替换成合适的目录。

前端使用

前端文件引用均使用相对路径，将前端文件放到同一目录下即可。

前端在调用后端 api 时使用的是绝对路径，例如 /api/v1/hello。如需更改，可以修改后端 api.go 中的 apiMux 和 mux 的相关属性。

关于临时文件夹的说明

前端播放器中勾选了 Prepare ，后端将转码文件到临时文件夹，然后直链提供文件。这有助于修复网路不稳定时 TCP 链接断开，stream 模式下 ffmpeg 中断输出并且不能断点续传的问题。

临时文件夹管理器位于 internal/pkg/tmpfs 中，默认删除时间是 10 分钟。10分钟内如果没有对该临时文件的访问，则会删除此临时文件。

Change log

• v1.0.0 首个版本

后端 API 文档

说明中带有 stream 或 流 相关字样的，说明该 API 以 io.Copy 方式传输文件，不支持断点续传

无需返回数据的 API 将返回 OK，某些 API 可能会在 status 字段中返回详细的执行信息。

{
    "status": "OK"
}

公开 API

• /api/v1/hello OK 测试

• /api/v1/get_file 以流方式获取文件

  • 请求示例

    {
        "id": 123
    }
    

• /api/v1/get_file_direct http 标准方式获取文件，支持断点续传，由 http.ServeFile 实现

  • 请求示例

    /api/v1/get_file_direct?id=30

• /api/v1/search_files 搜索文件

  • 请求示例

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

    搜索所有文件名中包含 "miku" 的文件

    limit 限制返回结果的数量，该值必须在 0~10 之间

    offset 是返回结构的偏移量，用于实现翻页功能。

  • 返回示例

    {
        "files": [
            {
                "id": 30,
                "folder_id": 100,
                "folder_name": "wonderful",
                "filename": "memories.flac",
                "filesize": 1048576
            },
            {
                "id": 30,
                "folder_id": 100,
                "folder_name": "wonderful",
                "filename": "memories.flac",
                "filesize": 1048576
            }
        ]
    }
    

    id 为文件的唯一标识

    folder_id 为该文件所在的文件夹标识

    foldername 为该文件所在的文件夹名

    filename 为该文件名

    filesize 为该文件的大小，单位字节

• /api/v1/search_folders 搜索文件夹

  • 请求示例

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

    搜索所有文件夹名中包含 "miku" 的文件夹。

    limit 限制返回结果的数量，该值必须在 0~10 之间

    offset 是返回结构的偏移量，用于实现翻页功能。

  • 返回示例

    {
        "folders": [
            {
                "id": 100,
                "foldername": "folder name"
            },
            {
                "id": 100,
                "foldername": "folder name"
            }
        ]
    }
    

    id 为该文件夹的唯一标识

    foldername 为该文件夹的名字

• /api/v1/get_files_in_folder 获取指定文件夹中的所有文件

  • 请求示例

    {
        "folder_id": 123,
        "limit": 10,
        "offset": 0
    }
    

  • 返回示例

    同 /api/v1/search_files

• /api/v1/get_random_files

  此 API 随机返回 files 表中 10 个文件。请注意，该操作会造成全表查询，在 AMD 2200G CPU 40000条数据记录情况下最大处理量为 100 请求每秒。

  • 请求示例

    直接 GET /api/v1/get_random_files

  • 返回示例

    同 /api/v1/search_files

• /api/v1/get_file_stream

  以流方式返回文件

  • 请求示例

    GET /api/v1/get_file_stream?id=123

• /api/v1/get_ffmpeg_config_list

  获取 ffmpeg 配置列表

  • 请求示例

    GET /api/v1/get_ffmpeg_config_list

  • 返回示例

    {
        "ffmpeg_configs": {
            "OPUS 256k": {"args": "-c:a libopus -ab 256k"},
            "WAV": {"args": "-c:a wav"}
        }
    }
    

• /api/v1/feedback 反馈

  • 请求示例

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

  • 返回 OK

• /api/v1/get_file_info 获取单个文件的信息

  • 请求示例

    {
        "ID": 123
    }
    

  • 返回示例

    {
        "id": 30,
        "folder_id": 100,
        "folder_name": "wonderful",
        "filename": "memories.flac",
        "filesize": 1048576
    },
    

• /api/v1/get_file_stream_direct 获取已提前转码好的文件，该 API 支持断点续传

  • 请求示例

    GET /api/v1/get_file_stream_direct?id=123&config=OPUS 128k

• /api/v1/prepare_file_stream_direct 请求提前转码文件，该 API 将返回转码后的文件大小

  • 请求示例

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

  • 返回示例

    {
        "filesize": 1973241
    }
    

需要 token 的 API

• /api/v1/walk 遍历目录，并将文件和文件夹添加到数据库中

  • 请求示例

    {
        "token": "your token",
        "root": "/path/to/root",
        "pattern": [".wav", ".flac"]
    }
    

    token 此 API 需要 token

    root 遍历目录

    pattern 文件扩展名列表（包含 . ），匹配扩展名的文件才会被添加到数据库

  • 返回 OK

• /api/v1/reset 重置数据库（feedbacks 不会清空）

  • 请求示例

    {
        "token": "your token"
    }
    

  • 返回 OK

• /api/v1/add_ffmpeg_config 添加 ffmpeg 配置

  注意：目前前端中没有实现此功能

  • 请求示例

    {
        "token": "your token",
        "name": "OPUS",
        "ffmpeg_config": {
            "args": "-c:a libopus -ab 256k"
        }
    }
    

    name 该配置的名字

    ffmpeg_config 一个 ffmpeg 的配置

    args 该 ffmpeg 配置的参数

  • 返回 OK

• /web/* 返回程序同目录下 web 文件夹中的内容

  此 api 仅用于方便开发，项目根目录中 web 文件夹中的内容并不是生产用（for production）的 js 文件，这个 API 不应该用来提供前端的 web 服务，web 服务应该由其他程序负责（例如 apache caddy nginx 等）

前端 API 文档

前端只有少量 API ，允许用户直接打开链接就执行某些功能

• /web/#/share?id=39

  分享文件，id 是文件的唯一标识。

• /web/#/search_folders?folder_id=2614

  显示该文件夹中的文件， folder_id 是文件夹的唯一标识。