文档中心
音乐资源接口说明
获取歌曲与歌词资源接口说明

获取歌曲与歌词资源接口说明

更新时间：2022-11-11 14:35

接口	方法名	详情描述
获取包含人声的歌曲资源	requestSong	获取 songID 对应包含人声的歌曲的资源，包括歌曲时长、歌手名、resource_id、share_token 等，我们也称为点歌。
获取歌曲伴奏资源	requestAccompaniment	获取 songID 对应歌曲的伴奏资源，包括歌曲资源个数、resource_id、krc_token、share_token 等。
获取歌曲伴奏的高潮片段资源	requestAccompanimentClip	获取 songID 对应歌曲高潮片段的资源，包括高潮片段的开始与结束时间、resource_id、krc_token、share_token 等。
获取其他用户分享的歌曲资源	getMusicByToken	通过其他用户分享的 share_token 获取到对应歌曲资源
获取逐行歌词	getLrcLyric	获取 songID 对应歌曲的逐行歌词。逐行歌词指的是根据歌曲/伴奏/高潮片段播放进度，将匹配的歌词一行行的展示。
获取逐字歌词	getKrcLyricByToken	我们可以通过 requestAccompaniment、requestAccompanimentClip、getMusicByToken 接口获取到 krc_token，再调用 getKrcLyricByToken 接口获取到逐字歌词。逐字歌词指的是在歌曲/伴奏/高潮片段播放时，先出现逐行歌词，然后对应播放节奏，将歌词的每个字进行高亮显示。

获取歌曲/伴奏/高潮片段资源中的 resource_id，只在 SDK 的生命周期内有效。其他用户如需获取对应的音乐资源，必须通过歌曲/伴奏/高潮片段资源中的 share_token，调用 getMusicByToken 接口获取对应的 resource_id。

1 获取歌曲资源

1.1 获取包含人声的歌曲资源

用户调用 requestSong 接口点歌，通过 ZegoCopyrightedMusicRequestSongCallback 回调结果，可以获取 songID 对应歌曲的资源，包括歌曲时长、歌手名、resource_id、share_token 等。

接口调用示例

以 iOS 端接口调用为例：

[self.copyrightedMusic requestSong:config callback:^(int errorCode, NSString * _Nonnull resource) {

}];

回调结果

参数	类型	描述
code	Number	返回码，具体请参见错误码，如查询不到可联系 ZEGO 技术支持。
message	String	操作结果描述。
request_id	String	请求 ID。
data	Object	响应数据。
└ is_accompany	Int	是否为伴奏。 0：歌曲 1：伴奏
└ song_name	String	歌曲名。
└ singer_name	String	歌手名。
└ song_id	String	歌曲 ID。
└ duration	Int	歌曲时长，单位：毫秒。
└ token_ttl	Int	share_token 有效时长，默认值为 3600000 毫秒（1 小时）。
└ resources_size	Int	歌曲资源数，resources 中资源个数。
└ resources	Object	歌曲资源信息。
└ resource_id	String	歌曲资源 ID。
└ song_size	Int	歌曲资源大小，单位：字节。
└ quality	String	歌曲音质。 nomal：标准 hq：高清 sq：无损
└ share_token	String	标准音质分享 token。

回调示例

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "is_accompany": 0,
    "song_name": "string",
    "singer_name": "string",
    "song_id": "string",
    "duration": 0,
    "token_ttl": 0,
    "resources_size": 1,
    "resources": [
      {
        "resource_id": "string",
        "size": 0,
        "quality": "string",
        "share_token": "string"
      }
    ]
  }
}

1.2 获取歌曲伴奏资源

用户调用 requestAccompaniment 接口点伴奏，通过 ZegoCopyrightedMusicRequestAccompanimentCallback 回调结果，可以获取 songID 对应歌曲的伴奏资源，包括歌曲资源个数、resource_id、krc_token、share_token 等。

接口调用示例

以 iOS 端接口调用为例：

[self.copyrightedMusic requestAccompaniment:config callback:^(int errorCode, NSString * _Nonnull resource) {

}];

回调结果

参数	类型	描述
code	Number	返回码，具体请参见错误码，如查询不到可联系 ZEGO 技术支持。
message	String	操作结果描述。
request_id	String	请求 ID。
data	Object	响应数据。
└ has_original	Int	伴奏是否有原唱。 0：没有 1：有
└ is_accompany	Int	是否为伴奏。 0：歌曲 1：伴奏
└ song_id	String	歌曲 ID。
└ duration	Int	歌曲时长，单位：毫秒。
└ krc_token	String	获取逐字歌词所需的 krc_token。
└ krc_token_ttl	Int	逐字歌词 krc_token 的有效期，默认值为 43200000 毫秒（12 小时）。
└ token_ttl	Int	share_token 有效时长，默认值为 3600000 毫秒（1 小时）。
└ resources_size	Int	歌曲资源数，resources 中资源个数。
└ resources	Object	歌曲资源信息。
└ resource_id	String	歌曲资源 ID。
└ size	Int	歌曲资源大小，单位：字节。
└ quality	String	歌曲音质。 nomal：标准 hq：高清 sq：无损
└ share_token	String	分享 token。

回调示例

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "has_original": 1,
    "is_accompany": 1,
    "song_id": "string",
    "share_token": "eyJhbGciOiJIUzI1NiIsInR5c",
    "duration": 0,
    "token_ttl": 0,
    "krc_token":"string",
    "krc_token_ttl":0,
    "resources_size": 1,
    "resources": [
      {
        "resource_id": "string",
        "size": 0,
        "quality": "string",
        "share_token": "string"
      }
    ]
  }
}

1.3 获取歌曲伴奏的高潮片段资源

用户调用 requestAccompanimentClip 接口点高潮片段，通过 ZegoCopyrightedMusicRequestAccompanimentClipCallback 回调结果，可以获取 songID 对应歌曲的伴奏资源，包括高潮片段的开始与结束时间、resource_id、krc_token、share_token 等。

接口调用示例

以 iOS 端接口调用为例：

[self.copyrightedMusic requestAccompanimentClip:config callback:^(int errorCode, NSString * _Nonnull resource) {

}];

回调结果

参数	类型	描述
code	Number	返回码，具体请参见错误码，如查询不到可联系 ZEGO 技术支持。
message	String	操作结果描述。
request_id	String	请求 ID。
data	Object	响应数据。
└ is_clip	Int	是否为高潮片段。 0：否 1：是
└ is_accompany	Int	是否为伴奏。 0：歌曲 1：伴奏
└ song_id	String	歌曲 ID。
└ krc_token	String	获取逐字歌词所需的 krc_token。
└ krc_token_ttl	Int	逐字歌词 krc_token 的有效期，默认值为 43200000 毫秒（12 小时）。
└ token_ttl	Int	share_token 有效时长，默认值为 3600000 毫秒（1 小时）。该参数为旧版参数，与 share_token_ttl 新版参数含义相同，为了兼容早期接入客户使用。
└ share_token_ttl	Int	share_token 有效时长，默认值为 3600000 毫秒（1 小时）。该参数为新版参数，与 token_ttl 旧版参数含义相同，新接入客户主要使用该参数。
└ segment_begin	Int	高潮片段相对于原曲时长的开始时间戳，单位：毫秒。
└ segment_end	Int	高潮片段相对于原曲时长的结束时间戳，单位：毫秒。
└ prelude_duration	Int	高潮片段的前奏时间，单位：毫秒。
└ resources_size	Int	歌曲资源数，resources 中资源个数。
└ resources	Object	歌曲资源信息。
└ resource_id	String	歌曲资源 ID。
└ size	Int	歌曲资源大小，单位：字节。
└ quality	String	歌曲音质。 nomal：标准 hq：高清 sq：无损
└ share_token	String	分享 token。

回调示例

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "is_clip":1,
    "is_accompany":0,
    "krc_token":"UQIFmNmY3NbjZggIwNzFl",
    "krc_token_ttl":43200000,
    "song_id":"300785364",
    "share_token_ttl":3600000,
    "token_ttl":3600000,
    "segment_begin":133157,
    "segment_end":235337,
    "prelude_duration":5000,
    "resources_size":1,
    "resources":[
        {
            "resource_id":"z_301215364_3",
            "size":0,
            "quality":"normal",
            "share_token":"7878787SDASDASDASDASD.SADSDASDASDASDSADSASDASDASDASD.V-sT427morLeej5sYUXgQzEgNjQ-YAoShYHGy5dGFKI"
        }
    ]
}
}

1.4 获取其他用户分享的歌曲资源

用户在获取歌曲/伴奏/高潮片段资源成功后，可以得到对应的 shareToken，将 shareToken 分享给其他用户，其他用户调用 getMusicByToken 接口获取被分享的音乐资源，通过 ZegoCopyrightedMusicGetMusicByTokenCallback 回调结果，可以获取对应歌曲的 resource_id。

接口调用示例

以 iOS 端接口调用为例：

NSString *token = @"";

[self.copyrightedMusic getMusicByToken:token callback:^(int errorCode, NSString * _Nonnull resource) {

}];

1.4.1 获取歌曲资源

回调结果

参数	类型	描述
code	Number	返回码，具体请参见错误码，如查询不到可联系 ZEGO 技术支持。
message	String	操作结果描述。
request_id	String	请求 ID。
data	Object	响应数据。
└ is_accompany	Int	是否为伴奏。 0：歌曲 1：伴奏
└ song_name	String	歌曲名。
└ singer_name	String	歌手名。
└ song_id	String	歌曲 ID。
└ duration	Int	歌曲时长，单位：毫秒。
└ resources_size	Int	歌曲资源数，resources 中资源个数。
└ resources	Object	歌曲资源信息。
└ resource_id	String	歌曲资源 ID。
└ size	Int	歌曲资源大小，单位：字节。
└ quality	String	歌曲音质。 nomal：标准 hq：高清 sq：无损

回调示例

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "is_accompany": 0,
    "song_name": "string",
    "singer_name": "string",
    "song_id": "string",
    "duration": 0,
    "resources_size": 1,
    "resources": [
      {
        "resource_id": "string",
        "size": 0,
        "quality": "string"
      }
    ]
  }
}

1.4.2 获取伴奏资源

回调结果

参数	类型	描述
code	Number	返回码，具体请参见错误码，如查询不到可联系 ZEGO 技术支持。
message	String	操作结果描述。
request_id	String	请求 ID。
data	Object	响应数据。
└ has_original	Int	伴奏是否有原唱。 0：没有 1：有
└ is_accompany	Int	是否为伴奏。 0：歌曲 1：伴奏
└ song_id	String	歌手名。
└ krc_token	String	获取逐字歌词所需的 krc_token。
└ krc_token_ttl	Int	逐字歌词 krc_token 的有效期，默认值为 43200000 毫秒（12 小时）。
└ resources_size	Int	歌曲资源数，resources 中资源个数。
└ resources	Object	歌曲资源信息。
└ resource_id	String	标准音质歌曲资源 ID。
└ size	Int	标准音质歌曲资源大小，单位：字节。
└ quality	String	歌曲音质。 nomal：标准 hq：高清 sq：无损

回调示例

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "has_original": 1,
    "is_accompany": 1,
    "song_id": "string",
    "krc_token":"string",
    "krc_token_ttl":0,
    "resources_size": 1,
    "resources": [
      {
        "resource_id": "string",
        "size": 0,
        "quality": "string"
      }
    ]
  }
}

1.4.3 获取高潮片段资源

回调结果

参数	类型	描述
code	Number	返回码，具体请参见错误码，如查询不到可联系 ZEGO 技术支持。
message	String	操作结果描述。
request_id	String	请求 ID。
data	Object	响应数据。
└ is_clip	Int	是否为高潮片段。 0：否 1：是
└ is_accompany	Int	是否为伴奏。 0：歌曲 1：伴奏
└ song_id	String	歌曲 ID。
└ krc_token	String	获取逐字歌词所需的 krc_token。
└ krc_token_ttl	Int	逐字歌词 krc_token 的有效期，默认值为 43200000 毫秒（12 小时）。
└ token_ttl	Int	share_token 有效时长，默认值为 3600000 毫秒（1 小时）。该参数为旧版参数，与 share_token_ttl 新版参数含义相同，为了兼容早期接入客户使用。
└ share_token_ttl	Int	share_token 有效时长，默认值为 3600000 毫秒（1 小时）。该参数为新版参数，与 token_ttl 旧版参数含义相同，新接入客户主要使用该参数。
└ segment_begin	Int	高潮片段相对于原曲时长的开始时间戳，单位：毫秒。
└ segment_end	Int	高潮片段相对于原曲时长的结束时间戳，单位：毫秒。
└ prelude_duration	Int	高潮片段的前奏时间，单位：毫秒。
└ resources_size	Int	歌曲资源数，resources 中资源个数。
└ resources	Object	歌曲资源信息。
└ resource_id	String	歌曲资源 ID。
└ size	Int	歌曲资源大小，单位：字节。
└ quality	String	歌曲音质。 nomal：标准 hq：高清 sq：无损
└ share_token	String	分享 token。

回调示例

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "is_clip":1,
    "is_accompany":0,
    "krc_token":"UQIFmNmY3NbjZggIwNzFl",
    "krc_token_ttl":43200000,
    "song_id":"300785364",
    "share_token_ttl":3600000,
    "token_ttl":3600000,
    "segment_begin":133157,
    "segment_end":235337,
    "prelude_duration":5000,
    "resources_size":1,
    "resources":[
        {
            "resource_id":"z_301215364_3",
            "size":0,
            "quality":"normal",
            "share_token":"7878787SDASDASDASDASD.SADSDASDASDASDSADSASDASDASDASD.V-sT427morLeej5sYUXgQzEgNjQ-YAoShYHGy5dGFKI"
        }
    ]
}
}

2 获取歌词

2.1 获取逐行歌词

用户调用 getLrcLyric 接口，通过 ZegoCopyrightedMusicGetLrcLyricCallback 回调结果，可以获取逐行歌词信息。

接口调用示例

以 iOS 端接口调用为例：

NSString *songID = @"";

[self.copyrightedMusic getLrcLyric:songID callback:^(int errorCode, NSString * _Nonnull lyrics) {

}];

回调结果

参数	类型	描述
lines	Object	逐行歌词。
└ begin_time	Int	当前行歌词开始时间，单位：毫秒。
└ end_time	Int	当前行歌词结束时间，单位：毫秒。
└ content	String	歌词内容。
lrc_format	String	lrc 格式歌词。

其他字段为歌词源文件中的 title 字段，不同的歌词文件中不一定存在，一般可以选择忽略。具体如下：

参数	类型	描述
al	String	唱片集。
ar	String	歌手。
au	String	歌词作者。
by	String	歌词文件创建者。
offset	Int	以毫秒为单位、加快（+）或延后（-）歌词播放。
lenght	Int	歌曲时长，单位：毫秒。
re	String	创建歌词文件的播放器或编辑器。
ti	String	歌词标题。
ve	String	程序版本。

回调示例

{
  "lines": [
    {
      "begin_time": 0,
      "end_time": 0,
      "content": ""
    }
  ],
  "lrc_format": "string",
  "al": "",
  "ar": "",
  "au": "",
  "by": "",
  "offset": 0,
  "lenght": 0,
  "re": "",
  "ti": "",
  "ve": ""
}

2.2 获取逐字歌词

用户先通过 requestAccompaniment、requestAccompanimentClip、getMusicByToken 接口获取到 krc_token，再调用 getKrcLyricByToken 接口，通过 ZegoCopyrightedMusicGetKrcLyricByTokenCallback 回调结果，可以获取逐字歌词信息。

接口调用示例

以 iOS 端接口调用为例：

NSString *krcToken = @"";

[self.copyrightedMusic getKrcLyricByToken:krcToken callback:^(int errorCode, NSString * _Nonnull lyrics) {

}];

回调结果

参数	类型	描述
lines	Object	SDK 解析后的歌词。
└ begin_time	Int	行开始时间，单位：毫秒。
└ duration	Int	行持续时间，单位：毫秒。此处与获取逐行歌词的参数格式不同。
└ content	String	歌词内容。
└ words	Object	逐字内容。
└ offset	Int	字偏移时间，单位：毫秒。字偏移指的是在歌词中该字的开始时间与该行开始时间对比的偏移。
└ duration	Int	字持续时间，单位：毫秒。
└ content	String	歌词内容。
krc_format_offset	Int	歌词偏移（使用歌词 UI 组件时需要），单位：毫秒。歌词偏移指的是歌词显示与歌曲音乐节奏上时间对比的偏移。
krc_format	String	krc 原格式歌词（一般不需要使用）。

其他字段为歌词源文件中的 title 字段，不同的歌词文件中不一定存在，一般可以选择忽略。具体如下：

参数	类型	描述
al	String	唱片集。
ar	String	歌手。
au	String	歌词作者。
by	String	歌词文件创建者。
lenght	Int	歌曲时长，单位：毫秒。
re	String	创建歌词文件的播放器或编辑器。
ti	String	歌词标题。
ve	String	程序版本。

回调示例

{

  "lines": [
    {
      "begin_time": 12076,
      "duration": 6158,
      "content": "string",
      "words": [
        {
          "offset": 0,
          "duration": 496,
          "word": "string"
        }
      ]
    }
  ],
  "krc_format_offset":0,
  "krc_format": "string",
  "al": "",
  "ar": "",
  "au": "",
  "by": "",
  "lenght": 0,
  "re": "",
  "ti": "",
  "ve": "",
}