ZegoCopyrightedMusic

2026-03-13

ZegoCopyrightedMusic

Declared in ZegoCopyrightedMusic.java

Methods

setEventHandler

public void setEventHandler(IZegoCopyrightedMusicEventHandler handler)

set copyrighted music event handler.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
handler	IZegoCopyrightedMusicEventHandler	The object used to receive copyrighted music callbacks.

Details

Set the callback function of the copyrighted music module, which can receive callback notifications related to song playback status .

When to call: After create the copyrighted music [createCopyrightedMusic].

Available since: 2.13.0

initCopyrightedMusic

public void initCopyrightedMusic(ZegoCopyrightedMusicConfig config, IZegoCopyrightedMusicInitCallback callback)

Initialize the copyrighted music module.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicConfig	the copyrighted music configuration.
callback	IZegoCopyrightedMusicInitCallback	init result

Details

Initialize the copyrighted music so that you can use the function of the copyrighted music later.

When to call: After call [createCopyrightedMusic] and [loginRoom].
Caution: 1. The real user information must be passed in, otherwise the song resources cannot be obtained for playback. 2. The user ID set when initializing copyrighted music needs to be the same as the user ID set when logging in to the room.

Available since: 2.13.0

getCacheSize

public long getCacheSize()

Get cache size.

Declared in ZegoCopyrightedMusic.java

When using this module, some cache files may be generated, and the size of the cache file can be obtained through this interface. Use case: Used to display the cache size of the App.

When to call: After initializing the copyrighted music [createCopyrightedMusic].

Available since: 2.13.0

cache file size, in byte.

clearCache

public void clearCache()

Clear cache.

Declared in ZegoCopyrightedMusic.java

When using this module, some cache files may be generated, which can be cleared through this interface. Use case: Used to clear the cache of the App.

When to call: After initializing the copyrighted music [createCopyrightedMusic].

Available since: 2.13.0

sendExtendedRequest

public  void sendExtendedRequest(String command, String params, IZegoCopyrightedMusicSendExtendedRequestCallback callback)

Send extended feature request.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
command	String	request command, details about the commands supported.
params	String	request parameters, each request command has corresponding request parameters.
callback	IZegoCopyrightedMusicSendExtendedRequestCallback	send extended feature request result

Details

Initialize the copyrighted music so that you can use the function of the copyrighted music later. Use case: Used to get a list of songs.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 2.13.0

getLrcLyric

public  void getLrcLyric(String songID, ZegoCopyrightedMusicVendorID vendorID, IZegoCopyrightedMusicGetLrcLyricCallback callback)

Get lyrics in lrc format.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
songID	String	the ID of the song or accompaniment, the song and accompaniment of a song share the same ID.
vendorID	ZegoCopyrightedMusicVendorID	Copyright music resource song copyright provider.
callback	IZegoCopyrightedMusicGetLrcLyricCallback	get lyrics result

Details

Get lyrics in lrc format, support parsing lyrics line by line. Use case: Used to display lyrics line by line.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 3.2.1

getLrcLyric

public void getLrcLyric(ZegoCopyrightedMusicGetLyricConfig config, IZegoCopyrightedMusicGetLrcLyricCallback callback)

Get lyrics in lrc format.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicGetLyricConfig	The configuration of get lyric.
callback	IZegoCopyrightedMusicGetLrcLyricCallback	get lyrics result

Details

Get lyrics in lrc format, support parsing lyrics line by line. Use case: Used to display lyrics line by line.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 3.12.0

getKrcLyricByToken

public void getKrcLyricByToken(String krcToken, IZegoCopyrightedMusicGetKrcLyricByTokenCallback callback)

Get lyrics in krc format.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
krcToken	String	The krcToken obtained when calling [requestResource] for accompaniment or climax clips, or when obtaining shared resources through the [getSharedResource] interface. For more details, please refer to /online-ktv-ios/client-api/apis-to-obtain-songs-and-lyrics#2_2
callback	IZegoCopyrightedMusicGetKrcLyricByTokenCallback	get lyrics result.

Details

Get verbatim lyrics, support parsing lyrics word by word. Use case: Used to display lyrics word by word.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 2.13.0

requestResource

public  void requestResource(ZegoCopyrightedMusicRequestConfig config, ZegoCopyrightedMusicResourceType type, IZegoCopyrightedMusicRequestResourceCallback callback)

Request music resource.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicRequestConfig	The configuration of requesting music resource.
type	ZegoCopyrightedMusicResourceType	The resource type of music.
callback	IZegoCopyrightedMusicRequestResourceCallback	Callback of requesting music resource.

Details

In addition to obtaining the basic information of the song (duration, song name, singer, etc.), and the most important resource id that can be used for local playback, there are also some related authentications information. Use case: Get copyrighted songs for local playback and sharing.

Related APIs: After a user in the room successfully calls this interface to request a music resource, other users in the room can call the [getsharedresource] interface to get the music resource for free once.
When to call: After initializing the copyrighted music [initCopyrightedMusic].
1. Each resource has a unique resource ID.
2. Every time this API is called, it will be billed once, please consult ZEGO business personnel for details.
3. Each resource has a unique resource ID. The resources obtained by calling this API are time-sensitive, the valid duration is the minimum value between the SDK life cycle and 24-hour.

Available since: 3.0.2

requestResource

public  void requestResource(ZegoCopyrightedMusicRequestConfigV2 config, IZegoCopyrightedMusicRequestResourceCallback callback)

Request music resource.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicRequestConfigV2	The configuration of requesting music resource.
callback	IZegoCopyrightedMusicRequestResourceCallback	Callback of requesting music resource.

Details

Related APIs: After a user in the room successfully calls this interface to request a music resource, other users in the room can call the [getsharedresource] interface to get the music resource for free once.
When to call: After initializing the copyrighted music [initCopyrightedMusic].
1. Each resource has a unique resource ID.
2. Every time this API is called, it will be billed once, please consult ZEGO business personnel for details.
3. Each resource has a unique resource ID. The resources obtained by calling this API are time-sensitive, the valid duration is the minimum value between the SDK life cycle and 24-hour.

Available since: 3.12.0

getSharedResource

public  void getSharedResource(ZegoCopyrightedMusicGetSharedConfig config, ZegoCopyrightedMusicResourceType type, IZegoCopyrightedMusicGetSharedResourceCallback callback)

Get shared music resource.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicGetSharedConfig	The configuration of getting shared music resource.
type	ZegoCopyrightedMusicResourceType	The resource type of music.
callback	IZegoCopyrightedMusicGetSharedResourceCallback	Callback of getting shared music resource.

Details

Related APIs: After a user in the room calls the [requestresource] interface to request a music resource successfully, other users in the room can call this interface to get the music resource for free once.
When to call: After initializing the copyrighted music [initCopyrightedMusic]. Each resource has a unique resource ID. The resources obtained by calling this API are time-sensitive, the valid duration is the minimum value between the SDK life cycle and 24-hour.

Available since: 3.0.2

getSharedResource

public  void getSharedResource(ZegoCopyrightedMusicGetSharedConfigV2 config, IZegoCopyrightedMusicGetSharedResourceCallback callback)

Get shared music resource.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicGetSharedConfigV2	The configuration of getting shared music resource.
callback	IZegoCopyrightedMusicGetSharedResourceCallback	Callback of getting shared music resource.

Details

Related APIs: After a user in the room calls the [requestresource] interface to request a music resource successfully, other users in the room can call this interface to get the music resource for free once.
When to call: After initializing the copyrighted music [initCopyrightedMusic]. Each resource has a unique resource ID. The resources obtained by calling this API are time-sensitive, the valid duration is the minimum value between the SDK life cycle and 24-hour.

Available since: 3.12.0

download

public void download(String resourceID, IZegoCopyrightedMusicDownloadCallback callback)

Download music resource.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the song or accompaniment.
callback	IZegoCopyrightedMusicDownloadCallback	download song or accompaniment result.

Details

Download music resource. It can only be played after downloading successfully. Use case: After obtaining the music resource authorization, use this interface to download the corresponding resources.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].
Caution: Downloading copyrighted music resources is affected by the Internet.

Available since: 2.13.0

cancelDownload

public void cancelDownload(String resourceID)

Cancel download of music resource.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the song or accompaniment.

Details

Cancel download of music resource. Use case: After starting to download music resources, use this interface to cancel the corresponding download task.

When to call: After starting the download [download].
Caution: When a valid resourceID is passed in, only unfinished download tasks will be cancelled. When empty is passed in, all unfinished download tasks will be canceled.

Available since: 3.11.0

queryCache

public boolean queryCache(ZegoCopyrightedMusicQueryCacheConfig config)

Query the resource's cache is existed or not.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicQueryCacheConfig	The configuration of querying cache.

Details

Query the resource is existed or not, query the Yinsuda resource cache by default Use case: Can be used to check the resource's cache is existed or not

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 3.9.0

queryCache

public boolean queryCache(ZegoCopyrightedMusicQueryCacheConfigV2 config)

Query the resource's cache is existed or not.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicQueryCacheConfigV2	The configuration of querying cache.

Details

Query the resource is existed or not, query the Yinsuda resource cache by default Use case: Can be used to check the resource's cache is existed or not

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 3.12.0

getDuration

public long getDuration(String resourceID)

Get the playing time of a song or accompaniment file.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the song or accompaniment.

Details

Get the playing time of a song or accompaniment file. Use case: Can be used to display the playing time information of the song or accompaniment on the view.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 2.13.0

setScoringLevel

public void setScoringLevel(int level)

Set the difficulty level of scoring.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
level	int	The difficulty level of scoring. The level ranges from 0 to 4. The scoring difficulty decreases from 0 to 4.

Details

Users can set the scoring difficulty level through this function.

When to call: After calling [initCopyrightedMusic] to initialize copyrighted music successfully, call [startScore] to start scoring.
Default value: When this function is not called, the difficulty level of scoring is 4.

Available since: 2.22.0
Restrictions: This function does not support dynamic settings. After calling this function successfully, the next call to [startScore] will take effect.

startScore

public int startScore(String resourceID, int pitchValueInterval)

Start scoring.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.
pitchValueInterval	int	the time interval of real-time pitch line callback, in milliseconds, the default is 50 milliseconds.

Details

Start the scoring function.After starting scoring, the scoring result OnCurrentPitchValueUpdate callback will be received according to the set callback time interval. Use case: Can be used to display the singing score on the view.

When to call: After obtaining verbatim lyrics and playing the accompaniment resources of copyrighted music.

Available since: 2.15.0
Restrictions: Only support use this api after [startPublishingStream].

pauseScore

public int pauseScore(String resourceID)

Pause scoring.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.

Details

Pause ongoing scoring,will stop the [OnCurrentPitchValueUpdate] callback. Use case: You can call this interface to pause the scoring function while scoring.

When to call: It can be called while grading.

Available since: 2.15.0

resumeScore

public int resumeScore(String resourceID)

Resume scoring.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.

Details

Resume currently paused scoring. Use case: When there is currently paused scoring, this interface can be called to resume the scoring function.

When to call: It can be called when there is currently a paused scoring.

Available since: 2.15.0

stopScore

public int stopScore(String resourceID)

Stop scoring.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.

Details

End the current rating.The [OnCurrentPitchValueUpdate] callback will be stopped, but the average or total score can still be obtained normally. Use case: You can call this interface to end the scoring while scoring.

When to call: It can be called while grading.

Available since: 2.15.0

resetScore

public int resetScore(String resourceID)

Reset scoring.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.

Details

Reset the scores that have already been performed,The [OnCurrentPitchValueUpdate] callback will be stopped and the average or total score will be 0. Use case: Often used in scenes where the same song is re-sung.

When to call: It can be called after scoring has been performed.

Available since: 2.15.0

getPreviousScore

public int getPreviousScore(String resourceID)

Get the score of the previous sentence.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.

Details

Get the score of the previous sentence. Use case: Can be used to display the score of each sentence on the view.

When to call: It can be called after playing the copyright accompaniment or accompaniment clip and starting to score.

Available since: 2.15.0

getAverageScore

public int getAverageScore(String resourceID)

Get average score.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.

Details

Get the average score. Use case: Can be used to display the average score on the view.

When to call: It can be called after playing the copyright accompaniment or accompaniment clip and starting to score.

Available since: 2.15.0

getTotalScore

public int getTotalScore(String resourceID)

Get total score .

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.

Details

Get the total score. Use case: Can be used to display the total score on the view.

When to call: It can be called after playing the copyright accompaniment or accompaniment clip and starting to score.

Available since: 2.15.0

getFullScore

public int getFullScore(String resourceID)

Get full score .

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.

Details

Get the full score. Use case: Can be used to display the full score on the view.

When to call: It can be called after playing the copyright accompaniment or accompaniment clip and starting to score.

Available since: 3.0.2

getStandardPitch

public void getStandardPitch(String resourceID, IZegoCopyrightedMusicGetStandardPitchCallback callback)

Get standard pitch data.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the accompaniment or accompaniment clip.
callback	IZegoCopyrightedMusicGetStandardPitchCallback	get standard pitch data result.

Details

Get standard pitch data. Use case: Can be used to display standard pitch lines on the view.

Caution: Only accompaniment or climactic clip assets have pitch lines.

Available since: 2.15.0

getCurrentPitch

public int getCurrentPitch(String resourceID)

Get real-time pitch data.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
resourceID	String	the resource ID corresponding to the song or accompaniment.

Details

Get real-time pitch data. Use case: Can be used to display real-time pitch lines on the view.

When to call: It can be called after playing the copyright accompaniment or accompaniment clip and starting to score.

Available since: 2.15.0

requestSong

deprecated

public void requestSong(ZegoCopyrightedMusicRequestConfig config, IZegoCopyrightedMusicRequestSongCallback callback)

[Deprecated] Request a song. Deprecated since 3.0.2, please use the [requestResource] function instead.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicRequestConfig	request configuration.
callback	IZegoCopyrightedMusicRequestSongCallback	request a song result

Details

By requesting a song, you can not only obtain basic information about a song (such as duration, song name, and artist), but also obtain the resource ID for local playback, share_token for sharing with others, and related authentication information. Support by the time, by the user monthly, by the room monthly subscription three ways. Use case: Get copyrighted songs for local playback and sharing.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].
Caution: This interface will trigger billing. A song may have three sound qualities: normal, high-definition, and lossless. Each sound quality has a different resource file, and each resource file has a unique resource ID.

Available since: 2.13.0

Deprecated

Deprecated since 3.0.2, please use the [requestResource] function instead.

requestAccompaniment

deprecated

public  void requestAccompaniment(ZegoCopyrightedMusicRequestConfig config, IZegoCopyrightedMusicRequestAccompanimentCallback callback)

[Deprecated] Request accompaniment. Deprecated since 3.0.2, please use the [requestResource] function instead.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicRequestConfig	request configuration.
callback	IZegoCopyrightedMusicRequestAccompanimentCallback	request accompaniment result.

Details

You can get the accompaniment resources of the song corresponding to the songID, including resource_id, krc_token, share_token, etc. Supports click-by-point accompaniment. Use case: Get copyrighted accompaniment for local playback and sharing.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].
Caution: This interface will trigger billing.

Available since: 2.13.0

Deprecated

Deprecated since 3.0.2, please use the [requestResource] function instead.

requestAccompanimentClip

deprecated

public  void requestAccompanimentClip(ZegoCopyrightedMusicRequestConfig config, IZegoCopyrightedMusicRequestAccompanimentClipCallback callback)

[Deprecated] Request accompaniment clip. Deprecated since 3.0.2, please use the [requestResource] function instead.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
config	ZegoCopyrightedMusicRequestConfig	request configuration.
callback	IZegoCopyrightedMusicRequestAccompanimentClipCallback	request accompaniment clip result.

Details

You can get the accompaniment clip resources of the song corresponding to the songID, including resource_id, krc_token, share_token, etc. Supports accompaniment clips by pay-per-use. Use case: Get copyrighted accompaniment clip for local playback and sharing.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].
Caution: This interface will trigger billing.

Available since: 2.13.0

Deprecated

Deprecated since 3.0.2, please use the [requestResource] function instead.

getMusicByToken

deprecated

public void getMusicByToken(String shareToken, IZegoCopyrightedMusicGetMusicByTokenCallback callback)

[Deprecated] Get a song or accompaniment. Deprecated since 3.0.2, please use the [getSharedResource] function instead.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
shareToken	String	access the corresponding authorization token for a song or accompaniment.
callback	IZegoCopyrightedMusicGetMusicByTokenCallback	get a song or accompaniment result.

Details

After the user successfully obtains the song/accompaniment/accompaniment clip resource, he can get the corresponding shareToken, share the shareToken with other users, and other users call this interface to obtain the shared music resources. Use case: In the online KTV scene, after receiving the song or accompaniment token shared by the lead singer, the chorus obtains the corresponding song or accompaniment through this interface, and then plays it on the local end.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 2.13.0

Deprecated

Deprecated since 3.0.2, please use the [getSharedResource] function instead.

getLrcLyric

deprecated

public void getLrcLyric(String songID, IZegoCopyrightedMusicGetLrcLyricCallback callback)

[Deprecated] Get lyrics in lrc format. Deprecated since 3.2.1, please use the method with the same name with [vendorID] parameter instead.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
songID	String	the ID of the song or accompaniment, the song and accompaniment of a song share the same ID.
callback	IZegoCopyrightedMusicGetLrcLyricCallback	get lyrics result

Details

Get lyrics in lrc format, support parsing lyrics line by line. Use case: Used to display lyrics line by line.

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 2.13.0

Deprecated

Deprecated since 2.14.0, please use the method with the same name with [vendorID] parameter instead.

queryCache

deprecated

public boolean queryCache(String songID, ZegoCopyrightedMusicType type)

[Deprecated] Query the resource's cache is existed or not. Deprecated since 3.2.1, please use the method with the same name with [vendorID] parameter instead.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
songID	String	the ID of the song or accompaniment, the song and accompaniment of a song share the same ID.
type	ZegoCopyrightedMusicType	the song resource type.

Details

Query the resource is existed or not. Use case: Can be used to check the resource's cache is existed or not

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 2.13.0

Deprecated

Deprecated since 2.14.0, please use the method with the same name with [vendorID] parameter instead.

queryCache

deprecated

public boolean queryCache(String songID, ZegoCopyrightedMusicType type, ZegoCopyrightedMusicVendorID vendorID)

[Deprecated] Query the resource's cache is existed or not. Deprecated since 3.9.0, please use the method with the same name with [config] parameter instead.

Declared in ZegoCopyrightedMusic.java

Parameters

Name	Type	Description
songID	String	the ID of the song or accompaniment, the song and accompaniment of a song share the same ID.
type	ZegoCopyrightedMusicType	the song resource type.
vendorID	ZegoCopyrightedMusicVendorID	Copyright music resource song copyright provider.

Details

Query the resource is existed or not, query the Yinsuda resource cache by default Use case: Can be used to check the resource's cache is existed or not

When to call: After initializing the copyrighted music success [initCopyrightedMusic].

Available since: 3.2.1

Deprecated

Deprecated since 3.9.0, please use the method with the same name with [config] parameter instead.