Player – 音频播放引擎

Player模块实现HaaS平台的音频播放功能，具体接口和参数如下所示。

调用Player接口之前，你需要先完成声卡及Audio引擎的初始化工作，具体接口请参考 Snd 模块

---

使用示例

# coding=utf-8
from audio import Snd, Player

# 声卡codec驱动注册及audio引擎初始化
Snd.install_codec_driver()
Snd.init()

# 实例化音频播放引擎并创建播放句柄
p0 = Player()
p0.create()

# 设置音频播放音量为8，最小为0（静音），最大为10
p0.set_volume(8)

#设置播放音源
p0.set_source('fs:/sdcard/test.mp3')

#启动播放并等待播放结束
p0.start()
p0.wait_complete()

#释放播放引擎资源
p0.release()

#释放声卡及audio引擎资源
Snd.uninstall_codec_driver()
Snd.deinit()

函数接口

Player模块具体接口和参数如下所示。

---

Player.create()

创建播放器。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – ENXIO

Player.release()

释放由create函数创建的播放器。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.start()

开始音频播放，该接口为同步接口。程序会阻塞在该函数调用处，直到播放器正常启动后才返回。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.stop()

停止音频播放，该接口为同步接口。程序会阻塞在该函数调用处，直到播放器正常停止后才返回。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.pause()

暂停音频播放，该接口为同步接口。程序会阻塞在该函数调用处，直到播放器正常暂停后才返回。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.resume()

恢复音频播放，该接口为同步接口。程序会阻塞在该函数调用处，直到播放器正常恢复后才返回。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.complete()

等待当前播放完成，player进入standby状态。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.stop_async()

停止音频播放，该接口为异步接口。程序调用该函数后会立即返回，而不会阻塞在该函数调用处。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.pause_async()

暂停音频播放，该接口为异步接口。程序调用该函数后会立即返回，而不会阻塞在该函数调用处。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.resume_async()

恢复音频播放，该接口为异步接口。程序调用该函数后会立即返回，而不会阻塞在该函数调用处。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.set_source(source)

设置音频播放的音源，支持本地音源（data、sdcard）和URL音源。

参数

source(str) – 音频播放的音源;

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.clr_source()

清除音频播放的音源。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.set_stream(format, cache_enable, cache_size)

设置音频播放信息。

参数

• format(int) –

  音频格式, 可以选择的类型为:

  enum media_format_t
  

  MEDIA_FMT_UNKNOWN = 0,

  MEDIA_FMT_PCM,

  MEDIA_FMT_WAV,

  MEDIA_FMT_MP3,

  MEDIA_FMT_AAC,

  MEDIA_FMT_M4A,

  MEDIA_FMT_OGG,

  MEDIA_FMT_OPS,

  MEDIA_FMT_SPX,

  MEDIA_FMT_WMA,

  MEDIA_FMT_AMR,

  MEDIA_FMT_AMRWB,

  MEDIA_FMT_FLAC,

• cache_enable(int) – 是否允许使能缓存。0：禁止， 其他：允许

• cache_size(int) – 允许使能缓存情况下缓存的大小。

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.put_stream(buffer, nbytes)

填充音频数据到音频播放器, 播放内存流。示例:

p0.put_stream(bytearray([0,1,2,3,4,5,6,7,8,9]), 10)

参数

• buffer(bytearray) – 待播放的的音频数据

• nbytes(int) – 待播放的音频数据字节数

返回

实际填充的音频数据，不大于nbytes数据；负数代表填充失败。

引发

OSError – EINVAL

Player.clr_stream(flush)

停止内存流播放并释放资源。

参数

flush(int) – 是否需要等待缓存中的数据全部播放完毕，1表示等待播完，0表示立即停止:

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.set_pcminfo(rate, channels, bits, frames)

设置播放PCM数据时音频播放器的参数。

参数

• rate(int) – 音频采样率

• channels(int) – 音频通道数

• bits(int) – 音频位宽，取值范围为16，24或32，大部分音频为16.

• frames(int) – 音频帧字节数，对应DMA中断周期。每播放完成frames字节数据产生一次DMA中断。该值太小会持续产生DMA终端，太大会引入较大的音频播放延迟。

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.get_duration()

获取正在播放的文件总时长，单位为秒。

参数

空 –

返回

正在播放的文件总时长，单位为秒。

引发

OSError – EINVAL

Player.get_position()

获取播放进度，单位为秒。

参数

空 –

返回

播放进度，单位为秒

引发

OSError – EINVAL

Player.set_volume(volume)

设置播放音量。

参数

volume(int) – 音量等级，范围：0~10，0表示静音

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.get_volume()

获取当前播放音量。

参数

空 –

返回

获取到的当前播放音量

引发

OSError – EINVAL

Player.volume_range()

播放器支持的音量范围。

参数

空 –

返回

dictionary类型， {‘vol_min’: 0, ‘vol_max’: 10}

引发

OSError – EINVAL

Player.seek(seconds)

定位到指定位置开始播放。

参数

seconds(int) – 播放定位位置，单位：秒

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.playback(source)

设置播放器音源并启动播放。

参数

source(str) – 音频播放的音源，支持本地音源（data、sdcard）和URL音源。

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.wait_complete()

等待当前音频播放完毕。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.download(name)

下载URL音频文件到/sdcard/music文件夹。

参数

name(str) – 待下载音频文件URL信息

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.download_abort()

终止URL音频文件下载。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.cache_config(config_dict)

设置播放缓存区。示例:

p0.cache_config({'place': 1, 'mem_size': 512, 'file_path': '/sdcard/'})

参数

config_dict(dictionary) –

格式如示例所示，其中:

place表示缓存文件存放的路径信息：0-空，1-文件系统，2-内存系统;

mem_size表示缓存文件大小，单位是KB;

file_path表示缓存文件全路径;

返回

实际填充的音频数据，不大于nbytes数据；负数代表填充失败。

引发

OSError – EINVAL

Player.set_fade(in_ms, out_ms)

设置音频启动和停止的时候渐入渐出的时长，单位为毫秒。

参数

• in_ms(int) – 渐入时长

• out_ms(int) – 渐出时长

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.set_format(format)

设置音频格式。

参数

format(int) – 具体取值参考 set_stream

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.set_standby(msec)

设置播放器静默时间，单位为毫秒。

参数

msec(int) – 静默时间:

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.eq_enable(enable)

是否使能音频播放器均衡功能。

参数

enable(int) – 是否使能均衡: 0表示不使能，1表示使能

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.state_dump()

导出播放器当前播放状态。

参数

空 –

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.pcmdump_enable(enable)

是否使能导出播放器音频数据到指定目录，以便对音频播放数据分析。

参数

enable(int) – 是否使能导出功能: 0表示不使能，1表示使能

返回

0: 成功，其他: 失败

引发

OSError – EINVAL

Player.get_state()

获取播放器的状态。

参数

空 –

返回

播放器状态，取值范围如下:

enum player_state_t

PLAYER_STAT_IDLE = 0,

PLAYER_STAT_READY,

PLAYER_STAT_RUNNING,

PLAYER_STAT_PAUSED,

PLAYER_STAT_RESUME,

PLAYER_STAT_STOP,

PLAYER_STAT_COMPLETE,

PLAYER_STAT_SEEK_CPLT,

PLAYER_STAT_MEDIA_INFO,

PLAYER_STAT_SOURCE_INVALID,

PLAYER_STAT_FORMAT_UNSUPPORT,

PLAYER_STAT_ERROR,

引发

OSError – EINVAL

Player.get_delay()

获取播放器延迟信息，单位为毫秒。

参数

空 –

返回

播放器延迟。

引发

OSError – EINVAL

Player.get_mediainfo()

获取当前播放的音频文件信息。

参数

空 –

返回

当前音频文件信息，格式为dictionary：

‘name’: 名称

‘author’: 演唱者

‘album’: 专辑

‘year’: 发行年月

‘valid’: 有效性

‘type’: 音频类型

‘bitrate’: 音频码率

‘media_size’: 音频文件大小

‘duration: 音频文件时长

引发

OSError – EINVAL

Player.get_cacheinfo()

获取缓存信息。

参数

空 –

返回

缓存区信息，格式为dictionary，具体格式参考 cache_config。

引发

OSError – EINVAL

Player.format_support(format)

设置播放器支持的音源类型。

参数

format(int) – 音源类型，具体内容参考 set_stream

返回

0: 成功，其他: 失败。

引发

OSError – EINVAL