music

立即使用

基础类

authorizationForMusic requestAuthorization scanMusic copyToSandbox cancelCopyToSandbox cleanCach presentMusic

概述

在 iOS 端，系统自带有音乐播放的 App ，名字叫 Music。用户可以删除该 App，也可以在 Apple Store 搜索下载该 App。music 模块封装了 iOS 平台上访问音乐库的相关接口。通过本模块可以判断当前 App 访问音乐权限，并支持扫描并获取 Music 里的被授权的音频文件。注意，由于知识产权原因，并不是所有 Music 内的音频文件都能获取，从苹果音乐服务器下载的音频文件获取不到，只能获取通过电脑同步到 Music 这个 App 里的音频文件。

使用本模块，需在云编译时申请访问音乐库权限。否则调用本模块接口会闪退，上传 App Store 也会被拒。

authorizationForMusic

判断是否有访问音乐库权限

authorizationForMusic(callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. { 
  2.     status: ''      //字符串类型；权限详情，取值范围如下：
  3.                      //notDetermined： 用户从未选择过权限
  4.                      //restricted：无法使用音乐库服务，该状态用户无法改变
  5.                      //denied：户拒绝该应用使用音乐库服务
  6.                      //authorized：用户允许该程序访问音乐库
  7. }

示例代码

  1. var music = api.require('music');
  2. music.authorizationForMusic(function(ret) {
  3.     if (ret) {
  4.         alert(JSON.stringify(ret));
  5.     }
  6. });

可用性

iOS 系统

可提供的 1.0.0 及更高版本

requestAuthorization

请求访问音乐库权限

requestAuthorization(callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. { 
  2.     status: ''      //字符串类型；权限详情，取值范围如下：
  3.                      //notDetermined： 用户从未选择过权限
  4.                      //restricted：无法使用音乐库服务，该状态用户无法改变
  5.                      //denied：户拒绝该应用使用音乐库服务
  6.                      //authorized：用户允许该程序访问音乐库
  7. }

示例代码

  1. var music = api.require('music');
  2. music.requestAuthorization(function(ret) {
  3.     if (ret) {
  4.         alert(JSON.stringify(ret));
  5.     }
  6. });

可用性

iOS 系统

可提供的 1.0.0 及更高版本

scanMusic

扫描 Music 内的音频文件

scanMusic({params},callback(ret, err))

params

thumbnail：

  • 类型：JSON 对象
  • 描述：返回的缩略图(若不存在则返回空)大小，若不传本参数则不返回缩略图，注意返回缩略图会降低读取速度
  • 内部字段：
  1. {
  2.    width: ,      //（可选项）缩略图宽度；默认：72
  3.    height:       //（可选项）缩略图高度；默认：72
  4. }

iCloud：

  • 类型：布尔
  • 描述：是否包含 iCloud 音乐
  • 默认：false

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.      status: true,        //布尔型；是否获取成功 
  3.      audios:[{           //数组类型；获取的音频资源信息组成的数组
  4.        artist: '',       //字符串类型；音频作者
  5.        title: '',        //字符串类型；音频标题
  6.        url: '',          //字符串类型；音频地址
  7.        albumTitle: ''    //字符串类型；音频专辑
  8.        duration:,        //数字类型；音频时长；单位：毫秒
  9.        thumbnail:        //字符串类型；缩略图路径
  10.     }]
  11. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     code:1    //数字类型；错误码：
  3.               //1：无访问音乐库权限 
  4. }

示例代码

  1. var music = api.require('music');
  2. music.scanMusic({
  3.     thumbnail:{
  4.        width:72,
  5.        height:72
  6.     },
  7.     iCloud:false
  8. },function(ret, err) {
  9.     if (ret.status) {
  10.         api.alert({msg:JSON.stringify(ret)});
  11.     } else {
  12.         api.alert({msg:JSON.stringify(err)});
  13.     }
  14. });

可用性

iOS 系统

可提供的 1.0.0 及更高版本

copyToSandbox

将音乐库的音频文件拷贝到沙盒

copyToSandbox({params},callback(ret, err))

params

url：

  • 类型：字符串
  • 描述：音乐库音频文件路径，如：ipod-library://item/item.mp3?id=4559289265963493915

savePath：

  • 类型：字符串
  • 描述：（可选项）保存路径，要求本地路径（fs://），如：fs://music/m1.mp3
  • 默认：默认缓存路径

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.      status: true,       //布尔型；是否拷贝成功 
  3.      realPath:           //字符串类型；路径类型 
  4. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     code:1    //数字类型；错误码：
  3.               //1：url为空
  4.               //2：资源初始化失败 
  5.               //3：资源读取失败 
  6. }

示例代码

  1. var music = api.require('music');
  2. music.copyToSandbox({ 
  3.     url:'ipod-library://item/item.mp3?id=4559289265963493915'
  4. },function(ret, err) {
  5.     if (ret.status) {
  6.         api.alert({msg:JSON.stringify(ret)});
  7.     } else {
  8.         api.alert({msg:JSON.stringify(err)});
  9.     }
  10. });

可用性

iOS 系统

可提供的 1.0.0 及更高版本

cancelCopyToSandbox

取消音乐库的音频文件拷贝到沙盒

cancelCopyToSandbox(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.      status: true   //布尔型；true：取消成功，false：当前未有拷贝中的音频  
  3. }

示例代码

  1. var music = api.require('music');
  2. music.cancelCopyToSandbox(function(ret) {
  3.     if (ret.status) {
  4.         api.alert({msg:'取消成功'});
  5.     } else {
  6.         api.alert({msg:'当前未有拷贝中的音频'});
  7.     }
  8. });

可用性

iOS 系统

可提供的 1.0.0 及更高版本

cleanCach

清空缓存

cleanCach({params},callback(ret, err))

params

url：

  • 类型：字符串
  • 描述：清空的缓存的目标
  • 默认：all
  • 取值范围：
    • all：音频和缩略图
    • thumbnail：缩略图
    • audio：音频

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.      status: true,       //布尔型；是否清除成功  
  3. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     code:1    //数字类型；错误码： 
  3.     userInfo:'' //字符串类型；错误信息
  4. }

示例代码

  1. var music = api.require('music');
  2. music.cleanCach({ 
  3.     target:'all'
  4. },function(ret, err) {
  5.     if (ret.status) {
  6.         api.alert({msg:'清除成功'});
  7.     } else {
  8.         api.alert({msg:JSON.stringify(err)});
  9.     }
  10. });

可用性

iOS 系统

可提供的 1.0.0 及更高版本

presentMusic

弹出系统自带选择音频页面

presentMusic({params},callback(ret, err))

params

multiple：

  • 类型：字符串
  • 描述：是否多选
  • 默认：true

showsCloudItems：

  • 类型：字符串
  • 描述：是否显示云端资源
  • 默认：true

thumbnail：

  • 类型：JSON 对象
  • 描述：返回的缩略图(若不存在则返回空)大小，若不传本参数则不返回缩略图，注意返回缩略图会降低读取速度
  • 内部字段：
  1. {
  2.    width: ,      //（可选项）缩略图宽度；默认：72
  3.    height:       //（可选项）缩略图高度；默认：72
  4. }

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.       eventType:'show',   //字符串类型；交互事件类型
  3.                           //show：弹出选择界面
  4.                           //cancel：用户取消
  5.                           //selected：用户选择完成
  6.       audios:[{           //数组类型；获取的音频资源信息组成的数组，仅当 eventType 为 selected 时有值
  7.        artist: '',       //字符串类型；音频作者
  8.        title: '',        //字符串类型；音频标题
  9.        url: '',          //字符串类型；音频地址
  10.        albumTitle: ''    //字符串类型；音频专辑
  11.        duration:,        //数字类型；音频时长；单位：毫秒
  12.        thumbnail:        //字符串类型；缩略图路径
  13.     }]
  14. }

示例代码

  1. var music = api.require('music');
  2. music.presentMusic({ 
  3.     multiple:true,
  4.     showsCloudItems:true
  5. },function(ret) {
  6.     if (ret) {
  7.         api.alert({msg:JSON.stringify(ret)});
  8.     } 
  9. });

可用性

iOS 系统

可提供的 1.0.0 及更高版本