接口说明

接入必读

请先查看接入必读了解具体接入方式，再参考此文档完成接入。

功能介绍

DeepChorus为用户提供副歌检测能力，自动分析获取音乐的段落结构，发现音乐的副歌高潮部分，可用于音乐视频高光剪辑等场景。

• 输入：音频片段
• 输出：副歌检测的结果

接口说明

• 当前支持通过 HTTP 协议在线调用。
• 请求内容包括：
  • payload字段为将请求参数序列化后的json文本
  • data字段为将音频二进制文件按照base64格式编码（标准base64，RFC 4648）的文本
• 使用备注：

公共参数

参考详细说明功能调用-通用协议

配置参数

payload配置参数为json字符串格式

响应格式

HTTP响应Content-Type: application/json

• 响应结果payload为json字符串格式，json内容格式如下：
  payload包含三个对象字段："thumbnail" (高潮)、"chorus_segments"(副歌)、"raw_segments"(原始段落)。每个对象存的是一个list，结构包含以下字段：

  • interval: 段落的起点、终点秒数

    • start_prob: 起点的概率分数

    • end_prob: 终点的概率分数

    • chorus_prob: 整段落的副歌概率分数

    • duration: 段落的长度秒数

    • res_duration: 起点到整曲结束剩的余长度秒数

    字段	描述	类型
    thumbnail	置信度最大的一段高潮	array
    thumbnail.interval	段落的起点、终点秒数	array
    thumbnail.start_prob	起点的概率分数	number
    thumbnail.end_prob	终点的概率分数	number
    thumbnail.chorus_prob	整段落的副歌概率分数	number
    thumbnail.duration	段落的长度秒数	number
    thumbnail.res_duration	起点到整曲结束剩的余长度秒数	number
    chorus_segments	副歌	array
    chorus_segments.*	子结构的字段同thumbnail	-
    raw_segments	原始段落	array
    raw_segments.*	子结构的字段同thumbnail	-

    响应结果payload示例：

    {
      "frame_sec": 0.192,
      "thumbnail": [
        {
          "start_prob": 0.099719256,
          "end_prob": 0.04581437,
          "duration": 37.248,
          "interval": [
            212.73601,
            249.98401
          ],
          "res_duration": 57.024002,
          "chorus_prob": 0.86254287
        }
      ],
      "chorus_segments": [
        {
          "start_prob": 0.09299248,
          "end_prob": 0.02493893,
          "duration": 35.712,
          "interval": [
            54.528,
            90.24
          ],
          "res_duration": 215.232,
          "chorus_prob": 0.83274376
        },
        {
          "start_prob": 0.074075386,
          "end_prob": 0.037723586,
          "duration": 48.768,
          "interval": [
            117.888,
            166.656
          ],
          "res_duration": 151.872,
          "chorus_prob": 0.82471144
        },
        {
          "start_prob": 0.099719256,
          "end_prob": 0.04581437,
          "duration": 37.248,
          "interval": [
            212.73601,
            249.98401
          ],
          "res_duration": 57.024002,
          "chorus_prob": 0.86254287
        }
      ],
      "raw_segments": [
        {
          "start_prob": 0.055697553,
          "end_prob": 0.09299248,
          "duration": 0,
          "interval": [
            39.744,
            54.528
          ],
          "res_duration": 0,
          "chorus_prob": 0.31311455
        },
        ...
        {
          "start_prob": 0.049528554,
          "end_prob": 0.042224556,
          "duration": 0,
          "interval": [
            268.41602,
            269.568
          ],
          "res_duration": 0,
          "chorus_prob": 0.10143171
        }
      ]
    }
    
    

参考示例

调用方式为：POST /api/v1/invoke

Golang

// Code sample:
// use http client to invoke SAMI HTTP Service
package main

import (
   "bytes"
   "encoding/base64"
   "encoding/json"
   "fmt"
   "io/ioutil"
   "log"
   "net/http"
   "time"
)

type InvokeResponse struct {
   StatusCode int32   `form:"status_code,required" json:"status_code,required" query:"status_code,required"`
   StatusText string  `form:"status_text,required" json:"status_text,required" query:"status_text,required"`
   TaskId     string  `form:"task_id,required" json:"task_id,required" query:"task_id,required"`
   Namespace  string  `form:"namespace,required" json:"namespace,required" query:"namespace,required"`
   Payload    *string `form:"payload,omitempty" json:"payload,omitempty" query:"payload,omitempty"`
   Data       []byte  `form:"data,omitempty" json:"data,omitempty" query:"data,omitempty"`
   State      *string `form:"state,omitempty" json:"state,omitempty" query:"state,omitempty"`
}

const (
   domain = "https://sami.bytedance.com"

   // auth token
   appkey    = "your_appkey"

   // SAMI method
   version   = "v4"
   namespace = "DeepChorus"

   // dump output
   dataOutputFile    = "output.wav"
   payloadOutputFile = "output.json"
   isDump            = true
)

func main() {
   // Get token
   token := "your_token"

   // Construct HTTP request
   //   1. Read local audio file
   //   2. Set HTTP json body
   //   3. Do HTTP POST request
   audioPath := "/path/to/audio"
   content, err := ioutil.ReadFile(audioPath)
   if err != nil {
      log.Fatalf("failed to read file: %v", err)
   }
   data := base64.StdEncoding.EncodeToString(content)
   body := fmt.Sprintf(`{"data": "%v"}`, data)
   urlPath := fmt.Sprintf(
      "%v/api/v1/invoke?version=%v&token=%v&appkey=%v&namespace=%v",
      domain, version, token, appkey, namespace,
   )
   log.Printf("invoke request: %v", urlPath)

   // HTTP POST request
   start := time.Now()
   resp, err := http.Post(urlPath, "application/json", bytes.NewBuffer([]byte(body)))
   if err != nil {
      panic(err)
   }
   defer resp.Body.Close()

   // Parse HTTP response
   ret, err := ioutil.ReadAll(resp.Body)
   if err != nil || resp.StatusCode != http.StatusOK {
      panic(string(ret))
   }
   log.Printf("http invoke: cost=%vms, response: %v", time.Since(start).Milliseconds(), string(ret))

   // parse SAMI response
   samiResp := InvokeResponse{}
   payloadStr := ""
   if err = json.Unmarshal(ret, &samiResp); err != nil {
      log.Println("parse response failed", string(ret), err)
      panic(err)
   }
   if samiResp.Payload != nil {
      payloadStr = *samiResp.Payload
   }
   log.Printf("response task_id=%v, payload=%v, data=[%d]byte", samiResp.TaskId, payloadStr, len(samiResp.Data))
   if isDump && samiResp.Payload != nil {
      _ = ioutil.WriteFile(payloadOutputFile, []byte(*samiResp.Payload), 0644)
   }
   if isDump && len(samiResp.Data) > 0 {
      _ = ioutil.WriteFile(dataOutputFile, samiResp.Data, 0644)
   }
}

Python

import base64
import json
import sys

import requests

# Construct HTTP request
payload = json.dumps({"extra": {}})
with open("/path/to/audio", "rb") as f:
    data = f.read()
    data = base64.b64encode(data).decode('utf-8')
req = {
    "appkey": "your_appkey",
    "token": "your_token",
    "namespace": "DeepChorus",
    "payload": payload,
    "data": data
}

if __name__ == "__main__":
    # HTTP POST request
    resp = requests.post("https://sami.bytedance.com/api/v1/invoke", json=req)

    # Parse HTTP SAMI response
    try:
        sami_resp = resp.json()
        if resp.status_code != 200:
            print(sami_resp)
            sys.exit(1)
    except:
        print(resp)
        sys.exit(1)

    print("response task_id=%s status_code=%d status_text=%s" % (
        sami_resp["task_id"], sami_resp["status_code"], sami_resp["status_text"]), end=" ")
    if "payload" in sami_resp and len(sami_resp["payload"]) > 0:
        print("payload=%s" % sami_resp["payload"], end=" ")

常见问题

• 通用FAQ

• 通用状态码