接口说明

接入必读

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

功能介绍

BeatTracking 为用户提供节拍检测能力，自动分析获取音乐的节拍点，发现音乐的更多信息，辅助音乐资源利用。

• 输入：音乐片段
• 输出：节拍检测的结果

接口说明

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

公共参数

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

配置参数

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

示例：

{
   "audio_info": {
      "format": "mp3",
      "sample_rate": 24000,
      "channel": 1
   },
   "extra": {
       "group_result": false
   }
}

响应格式

HTTP响应Content-Type: application/json

• 响应结果payload为json字符串格式，json内容格式如下：（当结果为空时，表明未能检测到beat信息，请检查输入音频是否正确）

  • 当请求参数group_result=false时（默认）：

  字段	描述	类型
  beats	节拍信息	object array
  beats.time	节拍时间点	number
  beats.beat	节拍拍号，有1234四种类型，分别代表"强-弱-次强-弱"（1是强拍），永远是1234一个循环，1为循环的第一个节拍	number
  bpm	每分钟节拍数	number

  示例：

  {
    "beats": [
      {
        "time": 3.13,
        "beat": 1
      },
      {
        "time": 3.91,
        "beat": 2
      },
      // hide more beats... 
    ],
    "bpm": 78.00346
  }
  
  

  • 当请求参数group_result=true时，payload为聚合结果格式：

  字段	描述	类型
  time	所有节拍时间点	number array
  value	所有节拍拍号，拍号有1234四种类型，分别代表"强-弱-次强-弱"（1是强拍），永远是1234一个循环，1为循环的第一个节拍	number array
  bpm	每分钟节拍数	number

  示例：

  {
      "time":[0.06,0.64,1.22,1.78,2.34,2.9,3.47,4.04,4.62,5.19,5.76,6.35,6.92,7.5],
      "value":[1,2,3,4,1,2,3,4,1,2,3,4,1,2],
      "bpm":104.90464
  }
  
  

参考示例

调用方式为：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 = "BeatTracking"

	// 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": {"group_result": False}})
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": "BeatTracking",
    "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=" ")

Nodejs

const { readFileSync } = require("fs")
const got = require("got")

const buffer = readFileSync("path/to/audio")
const req = {
    appkey: "your_appkey",
    token: "your_token",
    data: buffer.toString("base64"),
};
(async () => {
    const resp = await got.post("https://sami.bytedance.com/api/v1/invoke", {
        json: req, 
    }).json();

    console.log(resp);
    //=> {…}
})();

常见问题

• 通用FAQ

• 通用状态码