蜗牛VR

DEVELOPMENT DOCUMENT

Snail播发器开发文档

Snail Player SDK for IOS 开发说明文档

1. 概述

snailplayer sdk 是一个适用于 iOS平台的360度全景播放器

SDK,支持直播(★为了更好的直播体验,蜗牛云愿意为您提供免费且优质的直播服务),点播以及本地文件播放,可以帮助开发者在应用中快速实现全景视频的播放效果。(★请移步Snail VR 官网 进行sdk认证,激活licence权限)

本sdk采用授权发布机制,请在网站http://vr.snail.com开发中心注册获取并获取授权,未授权sdk会有播放时长的限制。


文档下载 SnailPlayerSDK_iOS_v1.2.0

更新日志 声明

本sdk采用授权发布机制,请在网站http://vr.snail.com 开发中心注册获取并获取授权,未授权sdk会有播放时长的限制。

兼容性

2. 功能


3. SDK集成

3.1 系统及设备要求
iOS 8.0 及其以上
支持 armv7、arm64 CPU 架构
iPhone 4s 及以上设备
Xcode 开发工具

3.2 导入sdk

sdk 为打包的SnailPlayer.framework的动态库,请在使用时嵌入sdk到二进制文件中,详细参考Demo 工程


工程配置

在Info.plist 中添加App Transport Security Setting, Allow Arbitrary Loads: YES ,允许http 访问

 

3.3 使用步骤
step 1: 添加引用

 

import <SnailPlayer/SnailPlayer.h>
@property (nonatomic, strong) SnailPlayer * mPlayer;

 

step 2: 创建player

播放器定义有以下两种类别,根据需要播放的内容来选择创建普通播放器或者VR播放器
PLAYER_TYPE_SNAIL // 普通播放器
PLAYER_TYPE_SNAIL_VR // VR 播放器

 

@property (nonatomic, strong) SnailPlayer * mPlayer;
mPlayer = [SnailPlayer createPlayer: PLAYER_TYPE_SNAIL_VR]; //创建VR播放器

 

step 3: 设置播放路径

 [mPlayer setUrl: url]; //设置播放路径
[mPlayer setDecoderOption: PLAYER_DECODER_HARDWARE]; //设置硬件解码
[mPlayer setLogLevel: PLAYER_LOG_DEBUG]; //设置日志输出Debug级别

 

step 4: 侦听播放器通知

添加播放器各种通知侦听函数,用于处理各种播放器通知

 

 [[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(playerDidStateChange:)
name: SnailPlayerStateChangeNotification
object:nil]; //状态变更侦听

- (void) playerDidStateChange:(NSNotification*)notification
{
switch(player.state){
}
}

[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(playerDidEventNotify:)
name: SnailPlayerEventNotification
object:nil]; //播放器事件侦听

- (void) playerDidEventNotify:(NSNotification*)notification
{
NSDictionary *dic = notification.object;
int event = [[dic valueForKey:@"EventType"] intValue];
switch(event){
}
}

 

[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(playerDidErrorNotify:)
name: SnailPlayerErrorNotification
object:nil]; //错误侦听

- (void) playerDidErrorNotify:(NSNotification*)notification
{
NSDictionary *dic = notification.object;
int error = [[dic valueForKey:@"ErrorCode"] intValue];
switch(error){
}
}

 

step 5: 开始播放

 

 [mPlayer start];

 

播放器启动中状态变更为PLAYER_STARTING,成功启动播放后会触发SnailPlayerStateChangeNotification 通知,并将状态变更为PLAYER_STARTED,启动失败会触发SnailPlayerErrorNotification通知告知失败原因

3.4 SDK 播放器内部状态


4.接口说明

4.1创建及配置


id

createPlayer:( SnailPlayerType)type
创建播放器

void

setUrl:(NSURL*)url
设置url

void

setDecoderOption:( SnailPlayerDecoderOption) option
设置decoder

void

setLogLevel:( SnailPlayerLogLevel) logLevel
设置log等级

4.2 控制


void

start
启动

void

stop
停止

void

resume
继续播放

void

pause
暂停

void

Shutdown
关闭

void

setMute:(BOOL) mute
静音

void

setLoop:(BOOL) loop
循环

void

seekTo:( NSTimeInterval) msec
进度条拖动

void

setVrOption: (SnailPlayerVrOption) option key: (NSInteger) key
VR相关设定

void

setVrOptionFloat: (SnailPlayerVrOption) option key: (float) key
VR相关设定(浮点参数时使用)

void

updateTouchVectorX (float x, float y)
用户手指滑动向量(VR

 

4.3 播放信息


SnailPlayerPlayState

state
获取播放器状态

UIView*

View
获取视窗

NSTimeInterval

getCurrentPosition
获取播放位置

NSTimeInterval

getDuration
获取内容时长

NSInteger

getVideoWidth
获取视频宽度

NSInteger

getVideoHeight
获取视频高度

NSString*

getVersion
获取sdk版本号

NSDictionary*

getMetaData

SnailPlaybackInfo*

getPlaybackInfo
获取播放相关信息

4.4 通知


NSString *

SnailPlayerStateChangeNotification
播放器状态变更通知

NSString *

SnailPlayerEventNotification
播放器事件通知

NSString *

SnailPlayerErrorNotification
播放器错误通知

4.5 枚举定义
 播放器类别


PLAYER_TYPE_SNAIL

2D播放器

PLAYER_TYPE_SNAIL_VR

VR 播放器

 解码器类别


PLAYER_DECODER_DEFAULT

默认解码器

PLAYER_DECODER_SOFTWARE

软解码

PLAYER_DECODER_HARDWARE

硬解码(video toolbox)

 日志类别


PLAYER_LOG_UNKNOWN

最高级别

PLAYER_LOG_DEFAULT

Default级别

PLAYER_LOG_VERBOSE

Verbose级别

PLAYER_LOG_DEBUG

Debug级别

PLAYER_LOG_INFO

Info级别

PLAYER_LOG_WARN

Warning 级别

PLAYER_LOG_ERROR

Error 级别

PLAYER_LOG_FATAL

Fatal 级别

PLAYER_LOG_SILENT

关闭日志

vr 控制项


option

key

VR_EYE_MODE
单双目模式

VR_DOUBLE_EYE
双目

VR_SINGLE_EYE
单目

VR_SPLICE_FORMAT
视频剪切模式

VR_SF_2D
2D

VR_SF_3D_SBS
3D side by side

VR_SF_3D_OVER_UNDER
3D over/under

VR_DISPLAY_PROJECTION
显示模式

VR_DP_PLANE
平面

VR_DP_SPHERE
球体

VR_DP_DOME
半球

VR_NAVIGATION_MODE
导航模式

VR_NV_GYROSCAPE
陀螺仪导航

VR_NV_TOUCH
手动拖拽导航

VR_NV_GYROSCAPE_TOUCH
手动拖拽和陀螺仪共存导航

VR_SET_FOV
观察角度

整数

VR_SET_SCALE_FACTOR
比例缩放

浮点数 (建议范围0.5 - 2.0)

VR_RESET_ANGLE
复位主视角

 

 

获取metaData
player 播放成功后可以通过接口getMetaData 获取播放流的metadata信息

// stream meta data
#define METADATA_KEY_FORMAT               @"format"
#define METADATA_KEY_DURATION             @"duration"
#define METADATA_KEY_BITRATE              @"bitrate"

// video meta data
#define METADATA_KEY_VIDEO_BITRATE        @"video_bitrate"
#define METADATA_KEY_VIDEO_CODEC_NAME     @"video_codec_name"
#define METADATA_KEY_VIDEO_CODEC_PROFILE  @"video_codec_profile"
#define METADATA_KEY_VIDEO_WIDTH          @"video_width"
#define METADATA_KEY_VIDEO_HEIGHT         @"video_height"
#define METADATA_KEY_VIDEO_FPS_NUM        @"video_fps_num"
#define METADATA_KEY_VIDEO_FPS_DEN        @"video_fps_den"
#define METADATA_KEY_VIDEO_SAR_NUM        @"video_sar_num"
#define METADATA_KEY_VIDEO_SAR_DEN        @"video_sar_den"

// audio meta data
#define METADATA_KEY_AUDIO_BITRATE        @"audio_bitrate"
#define METADATA_KEY_AUDIO_CODEC_NAME     @"audio_codec_name"
#define METADATA_KEY_AUDIO_CODEC_PROFILE  @"audio_codec_profile"
#define METADATA_KEY_AUDIO_SAMPLE_RATE    @"audio_sample_rate"
#define METADATA_KEY_AUDIO_CHANNEL_LAYOUT @"audio_channel_layout"

NSDictionary* metaData = [player getMetaData];
[metaData objectForKey:METADATA_KEY_FORMAT] 

 

获取播放信息
player 播放成功后可以通过接口getPlaybackInfo  查看播放器当前各种信息

 

@interface SnailPlaybackInfo : NSObject
@property (nonatomic, assign)float avDelay;
@property (nonatomic, assign)float avDiff;
@property (nonatomic, assign)bool isVideoOnly;
@property (nonatomic, assign)bool isAudioOnly;
@property (nonatomic, assign)float playbackRate;
@property (nonatomic, assign)float videoOutputFps;
@property (nonatomic, assign)float videoDecodingFps;
@property (nonatomic, assign)NSString *videoDecoder;
@property (nonatomic, assign)NSString *audioDecoder;
@property (nonatomic, assign)int64_t videoBufferBytes;
@property (nonatomic, assign)int64_t audioBufferBytes;
@property (nonatomic, assign)int64_t audioBufferPackets;
@property (nonatomic, assign)int64_t videoBufferPackets;
@property (nonatomic, assign)int64_t videoBufferDuration;
@property (nonatomic, assign)int64_t audioBufferDuration;
@end 

 

播放器状态


PLAYER_IDLE

空闲

PLAYER_STARTING

启动中

PLAYER_STARTED

启动成功

PLAYER_PLAYING

播放中

PLAYER_PAUSED

暂停中

PLAYER_STOPPED

停止中

 

事件


PLAYER_EVENT_UNKNOWN

未知事件

PLAYER_EVENT_BUFFERING

缓冲中

PLAYER_EVENT_BUFFERED

缓冲结束

PLAYER_EVENT_PLAYBACK_FINISHED

播放结束

PLAYER_EVENT_AUTHORIZED

SDK已授权通知

PLAYER_EVENT_UNAUTHORIZED

SDK未授权通知

PLAYER_EVENT_NETWORK_VERIFYING_STARTED

SDK开始进行网络授权认证

PLAYER_EVENT_NETWORK_VERIFYING_FAILED

SDK网络授权认证操作失败(网络原因)

错误


PLAYER_ERROR_UNKNOWN

未知错误

PLAYER_ERROR_TIMEOUT

超时错误

PLAYER_ERROR_IO

IO错误

PLAYER_ERROR_INVALID_DATA

无效的播放数据

PLAYER_ERROR_ADEC

音频解码器错误

PLAYER_ERROR_VDEC

视频解码器错误

PLAYER_ERROR_EXIT

错误结束(直播中推流结束也会触发)

PLAYER_ERROR_RESTRICTED_URL

受限制的url
本sdk 只支持播放woniucloud域名的网络串

PLAYER_ERROR_RESTRICTED_TIME_ARRIVAL

限制时间到达
未授权的sdk支持持续播放5分钟,然后上报此错误

PLAYER_ERROR_HTTP_BAD_REQUEST

http 400 错误

PLAYER_ERROR_HTTP_UNAUTHORIZED

http 401错误

PLAYER_ERROR_HTTP_FORBIDDEN

http 403错误

PLAYER_ERROR_HTTP_NOT_FOUND

http 404错误

PLAYER_ERROR_HTTP_OTHER_4XX

http 4xx错误

PLAYER_ERROR_HTTP_SERVER_ERROR

http 5xx错误