音乐控制（TSMusic）

TopStepComKit iOS SDK 的音乐控制模块提供了完整的手表设备音乐管理功能，包括音乐列表获取、推送、删除，以及播放控制和音量调节。

前提条件

已初始化 TopStepComKit SDK
手表设备已连接并配对
用户已获得必要的权限

数据模型

属性名	类型	说明
`musicId`	`NSString *`	音乐的唯一标识符，用于识别和管理设备上的音乐
`filePath`	`NSString *`	音乐文件的本地路径，推送音乐时必须指向有效文件
`title`	`NSString *`	音乐标题，用于设备显示，最大 64 字节
`artist`	`NSString *`	艺术家名称，用于设备显示，最大 64 字节
`duration`	`NSTimeInterval`	音乐总时长（秒）
`currentTime`	`NSTimeInterval`	当前播放位置（秒），范围 0 到 duration
`playbackStatus`	`TSMusicPlaybackStatus`	当前播放状态（停止、播放中、暂停）

枚举与常量

枚举值	数值	说明
`TSMusicPlaybackStatusStopped`	0	音乐已停止
`TSMusicPlaybackStatusPlaying`	1	音乐正在播放
`TSMusicPlaybackStatusPaused`	2	音乐已暂停

回调类型

回调类型	签名	说明
`TSMusicListBlock`	`void (^)(NSArray<TSMusicModel > _Nullable musics, NSError *_Nullable error)`	音乐列表获取完成回调，返回音乐数组或错误信息

接口方法

获取设备上所有音乐列表

- (void)fetchAllMusics:(nonnull TSMusicListBlock)completion;

参数	类型	说明
`completion`	`TSMusicListBlock`	完成回调，返回所有音乐模型数组或错误信息

代码示例：

id<TSMusicInterface> musicInterface = [TSKitManager sharedInstance].musicInterface;
[musicInterface fetchAllMusics:^(NSArray<TSMusicModel *> * _Nullable musics, NSError * _Nullable error) {
    if (error) {
        TSLog(@"获取音乐列表失败: %@", error.localizedDescription);
    } else {
        TSLog(@"获取到 %lu 首音乐", (unsigned long)musics.count);
        for (TSMusicModel *music in musics) {
            TSLog(@"音乐: %@ - %@", music.title, music.artist);
        }
    }
}];

从设备删除指定音乐

- (void)deleteMusic:(TSMusicModel *)music completion:(nullable TSCompletionBlock)completion;

参数	类型	说明
`music`	`TSMusicModel *`	要删除的音乐模型，必须包含有效的 musicId
`completion`	`TSCompletionBlock`	完成回调，返回删除是否成功及错误信息

代码示例：

TSMusicModel *musicToDelete = [[TSMusicModel alloc] init];
musicToDelete.musicId = @"music_123";

[musicInterface deleteMusic:musicToDelete completion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"音乐删除成功");
    } else {
        TSLog(@"音乐删除失败: %@", error.localizedDescription);
    }
}];

向设备推送音乐

- (void)pushMusic:(TSMusicModel *)music
         progress:(nullable TSFileTransferProgressBlock)progress
          success:(nullable TSFileTransferSuccessBlock)success
          failure:(nullable TSFileTransferFailureBlock)failure;

参数	类型	说明
`music`	`TSMusicModel *`	要推送的音乐模型，必须包含指向有效音乐文件的 filePath
`progress`	`TSFileTransferProgressBlock`	进度回调，返回推送进度（0-100）及传输状态
`success`	`TSFileTransferSuccessBlock`	成功回调，推送完成时调用
`failure`	`TSFileTransferFailureBlock`	失败回调，推送失败或被取消时调用

代码示例：

TSMusicModel *musicToPush = [[TSMusicModel alloc] init];
musicToPush.filePath = @"/path/to/music.mp3";
musicToPush.title = @"示例音乐";
musicToPush.artist = @"示例艺术家";

[musicInterface pushMusic:musicToPush
                progress:^(NSInteger progress, TSFileTransferStatus status) {
    TSLog(@"推送进度: %ld%%, 状态: %ld", (long)progress, (long)status);
} success:^(TSFileTransferStatus status) {
    TSLog(@"音乐推送成功");
} failure:^(TSFileTransferStatus status, NSError * _Nullable error) {
    TSLog(@"音乐推送失败: %@", error.localizedDescription);
}];

取消正在推送的音乐

- (void)cancelPushMusic:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回取消是否成功及错误信息

代码示例：

[musicInterface cancelPushMusic:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"音乐推送已取消");
    } else {
        TSLog(@"取消失败: %@", error.localizedDescription);
    }
}];

播放音乐

- (void)playMusic:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回播放指令是否执行成功

代码示例：

[musicInterface playMusic:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"播放指令已发送");
    } else {
        TSLog(@"播放失败: %@", error.localizedDescription);
    }
}];

暂停音乐

- (void)pauseMusic:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回暂停指令是否执行成功

代码示例：

[musicInterface pauseMusic:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"暂停指令已发送");
    } else {
        TSLog(@"暂停失败: %@", error.localizedDescription);
    }
}];

播放下一首

- (void)playNextMusic:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回下一首指令是否执行成功

代码示例：

[musicInterface playNextMusic:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"下一首指令已发送");
    } else {
        TSLog(@"切换失败: %@", error.localizedDescription);
    }
}];

播放上一首

- (void)playPreviousMusic:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回上一首指令是否执行成功

代码示例：

[musicInterface playPreviousMusic:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"上一首指令已发送");
    } else {
        TSLog(@"切换失败: %@", error.localizedDescription);
    }
}];

提高音量

- (void)increaseVolume:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回增加音量指令是否执行成功

代码示例：

[musicInterface increaseVolume:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"音量增加指令已发送");
    } else {
        TSLog(@"增加音量失败: %@", error.localizedDescription);
    }
}];

降低音量

- (void)decreaseVolume:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回降低音量指令是否执行成功

代码示例：

[musicInterface decreaseVolume:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"音量降低指令已发送");
    } else {
        TSLog(@"降低音量失败: %@", error.localizedDescription);
    }
}];

设备静音

- (void)muteVolume:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回静音指令是否执行成功

代码示例：

[musicInterface muteVolume:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"设备已静音");
    } else {
        TSLog(@"静音失败: %@", error.localizedDescription);
    }
}];

取消设备静音

- (void)unmuteVolume:(nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	完成回调，返回取消静音指令是否执行成功

代码示例：

[musicInterface unmuteVolume:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"设备已取消静音");
    } else {
        TSLog(@"取消静音失败: %@", error.localizedDescription);
    }
}];

设置具体音量值

- (void)setVolume:(NSInteger)volume completion:(nullable TSCompletionBlock)completion;

参数	类型	说明
`volume`	`NSInteger`	目标音量值，取值范围 [0, 100]，超出范围的值将被截断
`completion`	`TSCompletionBlock`	完成回调，返回设置音量指令是否执行成功

代码示例：

[musicInterface setVolume:50 completion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"音量已设置为 50");
    } else {
        TSLog(@"设置音量失败: %@", error.localizedDescription);
    }
}];

注意事项

所有回调均在主线程执行，可直接更新 UI
推送音乐时，filePath 指向的文件必须存在且可读
删除音乐时，music 参数必须包含有效的 musicId
同时只能有一个音乐推送操作处于活动状态
音量值范围为 [0, 100]，超出范围的值将被自动截断
静音操作会保留当前音量值，取消静音时会恢复至静音前的音量
如果没有正在进行的推送操作，调用 cancelPushMusic 不会产生任何效果

前提条件​

数据模型​

枚举与常量​

回调类型​

接口方法​

获取设备上所有音乐列表​

从设备删除指定音乐​

向设备推送音乐​

取消正在推送的音乐​

播放音乐​

暂停音乐​

播放下一首​

播放上一首​

提高音量​

降低音量​

设备静音​

取消设备静音​

设置具体音量值​

注意事项​

前提条件

数据模型

枚举与常量

回调类型

接口方法

获取设备上所有音乐列表

从设备删除指定音乐

向设备推送音乐

取消正在推送的音乐

播放音乐

暂停音乐

播放下一首

播放上一首

提高音量

降低音量

设备静音

取消设备静音

设置具体音量值

注意事项