Music Structure Analysis

功能介绍

音乐结构分析能力，可以解析用户输入的流行音乐的结构，定位前奏、主歌、副歌、间奏、桥段、尾奏等区间段。输入音乐文件，输出解析后的结构结果

接口说明

请求方式： POST（HTTP）

请求地址： http://service-mqk0mc83-1257411467.bj.apigw.tencentcs.com/release/job

请求头： Content-Type: application/json

请求流程： 接口包括‘创建任务’，‘查询任务’。创建任务后，用户可以主动查询任务来知晓任务结果，也可以在创建任务时输入回调地址（callback），则任务在完成后会自动回调该地址

其他要求： 建议采用常见音频格式，如 mp3、wav；且输入文件为流行音乐

创建任务

参数说明

参数	是否必选	类型	说明
action	是	string	公共参数，此处为 CreateJob
secretId	是	string	公共参数，用户 SecretId
secretKey	是	string	公共参数，用户 secretKey
createJobRequest	是	object
- inputs	是	Array of Input	Input，输入结构体数组
- outputs	是	Array of Output	Output，输出结构体数组
- callback	否	string	回调地址，默认：不开启回调
- customId	否	string	用户自定义任务 ID，小于 64 字符
- timeout	否	int	任务超时时间，单位秒。超过超时时间后任务会被置为 ERROR

Input

参数	是否必选	类型	说明
url	否	string	源 url 地址，与 source 字段二选一填写
source	否	object	仓库源设置，与 url 字段二选一填写
- contentId	是	string	仓库 ID
- path	是	string	源路径

Output

参数	是否必选	类型	说明
inputSelectors	是	Array of int	该输出的输入源
smartContentDescriptor	是	SmartContentDescriptor	智能能力的描述，默认：空
- musicStructureAnalysis	是	object	音乐结构分析
-- structureAnalysis	是	bool	音乐结构分析开关

请求示例：

{
  "action": "CreateJob",
  "secretId": "{secretId}",
  "secretKey": "{secretKey}",
  "createJobRequest": {
    "customId": "{customId}",
    "callback": "{callback}",
    "inputs": [
      {
        "url": "{url}"
      }
    ],
    "outputs": [
      {
        "inputSelectors": [0],
        "smartContentDescriptor": {
          "musicStructureAnalysis": {
            "structureAnalysis": true
          }
        }
      }
    ]
  }
}

返回示例：

{
  "requestId": "ac004192-110b-46e3-ade8-4e449df84d60",
  "createJobResponse": {
    "job": {
      "id": "13f342e4-6866-450e-b44e-3151431c578b",
      "state": 1,
      "customId": "{customId}",
      "callback": "{callback}",
      "inputs": [
        {
          "url": "{url}"
        }
      ],
      "outputs": [
        {
          "inputSelectors": [0],
          "smartContentDescriptor": {
            "musicStructureAnalysis": {
              "structureAnalysis": true
            }
          }
        }
      ],
      "timing": {
        "createdAt": "1603432763000",
        "startedAt": "0",
        "completedAt": "0"
      }
    }
  }
}

State

值	含义
1	SUBMITTED
2	PROCESSING
3	COMPLETED
4	ERROR
5	CANCELED

获取任务信息

获取方式：分为主动获取和被动回调。

主动获取按照 id 的类别有两种查询接口，一种是根据用户自定义 id 查询，由于平台无法保证该 id 的唯一性，故返回 Job 数组（见 1）；另一种是通过创建任务后的回包中的 id 查询（见 2）
被动回调需要在创建任务时填写 callback 字段，平台在任务进入完成态（COMPLETED/ERROR）后会将 Job 结构体发送给 callback 所指的地址（见 3），平台方推荐使用被动回调的方式获取任务结果。

在音乐结构分析能力中，如果查询到的任务成功（state=3），则任务的 Output 中会携带 smartContentResult 结构体，其中的 musicStructureAnalysis 字段（MusicStructureAnalysisResult），存储结构分析的结果。

返回 MusicStructureAnalysisResult 字段说明

参数	类型	说明
chrous	Array of StartEndPair	副歌区间列表
verse	Array of StartEndPair	主歌区间列表
intro	Array of StartEndPair	前奏区间列表
inter	Array of StartEndPair	间奏区间列表
outro	Array of StartEndPair	尾奏区间列表
bridge	Array of StartEndPair	桥段区间列表

StartEndPair

参数	类型	说明
start	string	开始时间
end	string	结束时间

1. 主动查询，根据用户在新建任务时传入的自定义 customId 请求示例：

{
  "action": "ListJobs",
  "secretId": "{secretId}",
  "secretKey": "{secretKey}",
  "listJobsRequest": {
    "customId": "{customId}"
  }
}

返回示例：

{
  "requestId": "c9845a99-34e3-4b0f-80f5-f0a2a0ee8896",
  "listJobsResponse": {
    "jobs": [
      {
        "id": "a95e9d74-6602-4405-a3fc-6408a76bcc98",
        "state": 3,
        "customId": "{customId}",
        "callback": "{callback}",
        "timing": {
          "createdAt": "1610513575000",
          "startedAt": "1610513575000",
          "completedAt": "1610513618000"
        },
        "inputs": [{ "url": "{url}" }],
        "outputs": [
          {
            "inputSelectors": [0],
            "smartContentDescriptor": {
              "musicStructureAnalysis": {
                "structureAnalysis": true
              }
            },
            "smartContentResult": {
              "musicStructureAnalysis": {
                "chrous": [{ "start": "60.0", "end": "90.0" }],
                "verse": [{ "start": "10.0", "end": "60.0" }],
                "intro": [{ "start": "0.0", "end": "10.0" }],
                "inter": [],
                "outro": [{ "start": "90.0", "end": "100.0" }],
                "bridge": []
              }
            }
          }
        ]
      }
    ],
    "total": 1
  }
}

2. 主动查询，根据新建任务时回包带的 id 请求示例：

{
  "action": "GetJob",
  "secretId": "{secretId}",
  "secretKey": "{secretKey}",
  "getJobRequest": {
    "id": "{id}"
  }
}

返回示例：

{
  "requestId": "c9845a99-34e3-4b0f-80f5-f0a2a0ee8896",
  "getJobResponse": {
    "job": {
      "id": "a95e9d74-6602-4405-a3fc-6408a76bcc98",
      "state": 3,
      "customId": "{customId}",
      "callback": "{callback}",
      "timing": {
        "createdAt": "1610513575000",
        "startedAt": "1610513575000",
        "completedAt": "1610513618000"
      },
      "inputs": [{ "url": "{url}" }],
      "outputs": [
        {
          "inputSelectors": [0],
          "smartContentDescriptor": {
            "musicStructureAnalysis": {
              "structureAnalysis": true
            }
          },
          "smartContentResult": {
            "musicStructureAnalysis": {
              "chrous": [{ "start": "60.0", "end": "90.0" }],
              "verse": [{ "start": "10.0", "end": "60.0" }],
              "intro": [{ "start": "0.0", "end": "10.0" }],
              "inter": [],
              "outro": [{ "start": "90.0", "end": "100.0" }],
              "bridge": []
            }
          }
        }
      ]
    }
  }
}

3. 被动回调

会将进入完成态（COMPLETED/ERROR）的任务的整个 Job 结构体发送到用户在创建任务时指定的 callback 字段对应的地址，Job 结构体见主动查询的示例（getJobResponse 下）