빠른메뉴
컨텍정보
로그인

제품소개 회사소개 고객사 제품문의 제품관리

나클립스 모바일 플레이어 SDK(iOS 용) - 개발자 레퍼런스 가이드
1. 소프트웨어 사양
S/W 명칭 iOS 기반 나클립스 플레이어 모바일 SDK (Naclips Player Mobile SDK for iOS)
S/W 분류 어플리케이션 개발용 SDK(Software Development Kit) 프레임워크 라이브러리
개발 언어 / 개발 툴 Swift V4.0 / Xcode V9.4
적용 OS/Platform iOS System
S/W 패키지 구성 SDK 라이브러리(Nagent.framework), 샘플 소스
2. 라이브러리 클래스 구조.
Nagent-> cxNagent > cx_serv_retv > cx_media_inf
-> cxString
-> cxEtce > cx_media_type
3. 클래스별 기능 설명
cxNagent SDK 메인 클래스, 암호화된 나클립스 스트리밍 소스URL 쿼리 및 썸네일 이미지를 디바이스 캐시에 다운로드 한다.
cx_serv_retv 나클립스 VOD 서버 엔진으로부터 쿼리된 스트리밍 정보를 저장하고 관리하는 클래스.
cx_media_inf 나클립스 VOD 서버 엔진으로부터 쿼리된 미디어 파일의 헤더 정보가 저장되는 클래스.
cxString 문자열 관련 Static 함수를 저장하는 클래스.
cxEtce 기타 Static 함수를 저장하는 클래스.
cx_media_type 비디오 / 오디오 파일 확장자 쿼리 클래스.
4. 클래스별 메서드 목록
cxNagent
getPropertyBool(s_name:String)->Bool Bool 형의 프로퍼티 값을 가져온다. s_name 인자값은 setProperty 메서드 참조.
getPropertyInt(s_name:String)->Int int 형의 프로퍼티 값을 가져온다. s_name 인자값은 setProperty 메서드 참조.
getPropertyStr(s_name:String)->String String 형의 프로퍼티 값을 가져온다. s_name 인자값은 setProperty 메서드 참조.
getServerURL(s_name:String)->URL? 동영상 파일 위치 URL 또는 썸네일 이미지 디렉토리 위치 URL 값 가져옴.
getServretv()->cx_serv_retv cxNagent 클래스 객체의 cx_serv_retv 클래스 객체를 리턴.
getStatus()->T_RET cxNagent 클래스 객체의 현재 상태값을 가져온다.
getThumbnailPath(i_dx:Int)->String i_dx 번째 썸네일 이미지 파일의 디바이스 캐시 폴더에 저장된 위치를 가져온다.
getThumbnailSec(i_dx:Int)->Int i_dx 번째 썸네일 이미지에 해당하는 동영상 재생 위치 시간값을 가져온다.(초단위 시간)
getTimeoutConn()->Double cxNagent 클래스 객체에 설정된 서버 접속 타임아웃 시간값을 가져온다.(초단위 시간)
getTimeoutRecv()->Double cxNagent 클래스 객체에 설정된 데이터 수신 타임아웃 시간값을 가져온다.(초단위 시간)
prepareStream() cxNagent 객체의 auto_play 옵션의 비활성 되어 있을때, 수동으로 동영상 플레이를 시작한다.
prepareStream()은 나클립스 VOD 서버에 접속하여 암호화된 미디어 스트리밍 URL을 쿼리한다.
reset() 나클립스 서버에서 쿼리한 스트리밍 정보값을 초기화 한다.
setEvent(eventName:String, action: @escaping ((Any?)->())) eventName에 해당하는 이벤트 발생시 처리될 action 함수명을 등록한다. 이벤트명은 아래와 같다.
cxNagent.T_XEVT.SFX_GetEncuri : 암호화된 동영상 스트리밍 URL 쿼리 완료시.
cxNagent.T_XEVT.SFX_GetThumbs : 썸네일 이미지 파일을 서버로 부터 수신하여 저장 완료.
cxNagent.T_XEVT.SFX_ReturnError : 에러 발생시.
setProperty(s_name:String, v_value: Any)->Bool 프로퍼티 값을 cxNagent 객체의 입력한다. s_name 인자 값은 아래와 같다.
Int 형 프로퍼티.
cxNagent.T_PPID.IFX_MULBPSDX : 다중대역폭 스트리밍시, 대역폭별 파일 순서값.
cxNagent.T_PPID.IFX_TMBSRCDX : 다중대역폭 스트리밍시, 썸네일 이미지세트 순서값.
String 형 프로퍼티.
cxNagent.T_PPID.SFX_VODURL : 스트리밍할 동영상 파일 URL
cxNagent.T_PPID.SFX_IMGURL : 썸네일 이미지 디렉토리 URL
cxNagent.T_PPID.SFX_LICNKEY : SDK 라이센스 키값
setTimeout(r_conn:Double, r_recv:Double) 서버와 접속 및 데이터 수신 타임아웃 시간을 설정한다. -1은 설정값을 변경하지 않는 인자값이다.
var thumbnailCount: Int 서버에서 수신한 썸네일 이미지 갯수 프로퍼티 (get Type variable)
cx_serv_retv
getMediaFuid()->String 동영상 파일의 파일 Unique-ID 값. 썸네일 이미지 파일명 조합시 사용한다.
getMediaHeader()->cx_media_inf VOD 서버에서 쿼리된 동영상 파일 정보를 가져온다. cx_media_inf class는 아래와 같은 프로퍼티를 가지고 있다.
i_type(미디어 파일 타입:정수), i_kbps(초당전송률:Killobits/sec), r_filesize(파일크기: 실수), i_duration(재생시간:정수), s_audio4cc(오디오 압축방식:문자열 / 기본값:null), s_video4cc(비디오 압축방식:문자열 / 기본값:null)
getMediaUri()->URL? 암호화된 동영상 미디어 소스 URL을 가져온다.
getServVersion()->String 나클립스 VOD 서버의 엔진 버전을 가져온다.
getThumbCount()->Int 쿼리된 썸네일 이미지 갯수를 리턴한다.
getThumbName(i_dx: Int)->String i_dx 번째 썸네일 이미지 시간정보 문자열을 가져온다. getMediaFuid() 메서드의 리턴 문자열과 조합하여 디바이스 캐시에 저장된 실제 썸네일 이미지 파일명을 생성한다.
cxEtce
static SECP(r_sec:Double)->useconds_t 초단위 시간을 밀리초 단위 시간으로 변환한다.
static getLineCount(s_text:String, b_inc_blank:Bool,
         b_inc_last_line:Bool)->Int 		Text의 라인수를 가져온다.(b_inc_blank값이 true이면 문장의 행안에 글자가 없더라도 카운팅 한다. false 이면 행에 글자가 없으면 카운팅하지 않는다. b_inc_last_line 값이 true 이면 마지막 라인에 LF가 없더라도 행으로 간주하여 카운팅 한다.)
static shiftBytes(bs_array: inout [Byte], i_offset:Int) 입력된 바이트 배열을 i_offset 갯수만큼 밀어(잘라)낸다.
i_offset 양수이면 오른쪽으로 밀어내며(오른쪽을 자름), 음수이면 왼쪽으로 밀어낸다.
static timeToSec(s_hour:String, s_min:String,
         s_sec:String)->Int		 시간,분,초 숫자형 문자열을 입력하면 초단위 시간값을 리턴한다.
static StringToUrl(s_url:String, b_enc: Bool)->URL? 문자열을 URL로 바꾼다. b_enc는 변환시 URL인코딩 여부를 지정.
cxEtce
static isNilOrEmpty(_ s_var:String?)->Bool s_var 문자열이 nil 또는 Empty이면 참을 리턴한다.
static strcmp(_ s_a:String!,_ s_b:String!,_ b_ignore_case
         :Bool=false)->Bool 		문자열이 같은지 비교한다. (b_ignore_case 인수가 true 이면 대소문자 구분을 하지 않는다.)
cx_media_type
cx_media_type(i_type:Int) cx_media_type 클래스 생성자. i_type 인자는 Audio/Video 파일 타입의 숫자값이다.
(i_type값은 cx_serv_retv 클래스 객체의 getMediaHeader().i_type 값이다.)
setType(i_type:Int) cx_media_type 클래스 객체의 Audio/Video 파일 타입의 숫자값을 입력 또는 변경한다.
getType()->String 입력된 Audio/Video 파일 타입의 숫자 값에 해당하는 미디어 타입 확장자를 리턴하다.
getTypeDesc()->String 입력된 Audio/Video 파일 타입의 숫자 값에 해당하는 미디어 타입 문자열을 리턴한다.
5.데이터 타입별 확장목록 (Data Type Extension).
extension String
charAt(_ i_pt:Int)->Character 문자열에서 i_pt 번째 문자를 가져온다.
indexOf(_ c_key:Character,_ i_start:Int = -1)->Int 문자열에서 i_start 번째 부터 검사하여 c_key 문자를 찾는다.
indexOf(s_key:String)->Int 문자열에서 s_key 문자열을 검색한다.
isNumeric()->Bool 문자열이 숫자로만 이루어진 문자열인지 검사한다.
lastIndexOf(_ c_key:Character, i_start:Int = -1)->Int 문자열에서 c_key 문자를 뒤에서 부터 찾는다. 이때 i_start값은 뒤에서 부터 시작되는 순서값.
shift(i_count:Int)->String 문자열을 i_count 만큼 잘라낸다. i_count값이 양수이면 오른쪽, 음수이면 왼쪽을 자른다.
substr(i_start:Int, i_offset:Int = 0)->String 문자열에서 i_start 부터 시작하여 i_offset 갯수만큼의 문자열을 가져온다.
substring(i_start:Int, i_end:Int = -1)->String 문자열에서 i_start 부터 시작하여 i_end 이전 까지의 문자열을 가져온다.
trim()->String 문자열에서 바깥쪽 Space를 제거하여 가져온다.
var doubleValue: Double 숫자형 문자열이면 실수로 변환된 값을 가져온다. (get Type variable)
var numberParsed: Int 문자열 에서 숫자형 문자만 뽑아 정수로 변환한 값을 가져온다. (get Type variable)
var numberValue: Int 숫자형 문자열이면 정수로 변환된 값을 가져온다. (get Type variable)
extension URL
getScheme()->String URL의 Scheme 값을 가져온다. Default 값은 Empty
getHost()->String URL의 Host 값을 가져온다. Default 값은 Empty
getPort()->Int URL의 Port 값을 가져온다. Default 값은 0
getPath()->String URL의 Path 값을 가져온다. Default 값은 Empty
getQuery()->String URL의 Query 값을 가져온다. Default 값은 Empty
extension Character
var asciiValue: Int 문자의 아스키 값을 가져온다. (get Type variable)
extension UInt8
var asciiValue: Int 바이트의 아스키 값을 가져온다. (get Type variable)
extension Array where Element == Byte
indexOf(bs_key:[Byte], i_from:Int=0)->Int 바이트 배열에서 bs_key 배열을 i_from 번째부터 찾는다.
toString(_ s_encid:String.Encoding)->String 바이트 배열을 문자열로 변환한다. s_encid는 문자열 인코딩 타입.
6. SDK 라이브러리 적용 프로그래밍 요약.
1) Nagent 모듈 import.
Nagent 프레임워크를 새로운 프로젝트에 추가하고, 추가된 프레임워크 모듈을 소스상에 추가(import)하여 cxNagent 클래스 객체를 생성한다.
import Nagent
class ViewController UIViewController {
  .....
  let gx_nagent = cxNagent()
  .....
2) 클래스 객체에 프로퍼티 입력.
생성된 cxNagent 클래스 객체에 VOD 스트리밍을 위한 프로퍼티를 입력한다.
Override func viewDidLoad(){
  super.viewDidLoad()
  ....
  let s_vodurl = "assp://vod.nexpoly.co.kr/media/1st_sample.mp4"
  let s_imgurl = "cssp://www.nexpoly.co.kr/sample/"
  if !gx_nagent.setProperty(s_name: cxNagent.T_PPID.SFX_VODURL ,v_value: s_vodurl       ){ print("failed set - vodurl") }
  if !gx_nagent.setProperty(s_name: cxNagent.T_PPID.SFX_IMGURL ,v_value: s_imgurl       ){ print("failed set - imgurl") }
  if !gx_nagent.setProperty(s_name: cxNagent.T_PPID.SFX_LICNKEY,v_value: FX_SDKLICN_KEY ){ print("failed set - licensekey") }
  ....
3) cxNagent 클래스의 이벤트 처리 등록.
생성된 클래스 객체의 이벤트 처리 함수를 등록한다. 주의할 사항은 이벤트 처리함수는 별도의 자식 쓰레드(Child Thread)에서 실행된다는 점이다. 따라서 동영상 재생 및 썸네일 이미지를 이미지뷰 등에 디스플레이 할때는 DispatchQueue.main.async 루틴을 이용하여 메인 쓰레드로 복귀하여 실행하여야 한다는 점이다.
  ....
  gx_nagent.setEvent(eventName: cxNagent.T_XEVT.SFX_GetEncuri  , action: self.runEvtGetEncuri)   // 암호화된 스트리밍 URL 가져옴 완료 이벤트
  gx_nagent.setEvent(eventName: cxNagent.T_XEVT.SFX_GetThumbs  , action: self.runEvtGetThumbs)   // 썸네일 이미지 저장완료 이벤트
  gx_nagent.setEvent(eventName: cxNagent.T_XEVT.SFX_ReturnError, action: self.runEvtReturnError) // 에러 발생 이벤트
  ....
}
....
private func runEvtGetEncuri(option:Any?){
  guard let z_ret = option as? T_RET else {return}
  guard let z_url = cxEtce.StringToUrl(s_url: z_ret.s, b_enc: false) else {return}
  DispatchQueue.main.async { // 메인 쓰레드에서 실행하여야 함.
    self.playVideoOnAVplayer(z_url:z_url) // AVPlayer를 이용하여 동영상 소스 URL 스트리밍 처리.
  }
}
4) 스트리밍 플레이 시작.
cxNagent 클래스 객체의 prepareStream() 메서드를 실행하여 나클립스 VOD 스트리밍을 시작한다. prepareStream() 메서드가 실행되면, 클래스 객체는 아래와 같은 처리 루틴을 백그라운드 쓰레드에서 수행한다.
1> 클래스 객체는 나클립스 VOD 서버에 접속하여 암호화된 VOD 스트리밍 URL을 수신.
2> 스트리밍 URL을 수신완료 하면 GetEncuri 이벤트를 발생시키고 썸네일 이미지파일 쿼리 시작.
3> 만약 이미 썸네일 이미지가 디바이스 캐시에 저장되어 있으면 저장된 썸네일 파일의 업데이트 상황을 체크하여 Skip 또는 다운로드.
4> 썸네일 이미지 Skip 또는 다운로드가 완료되면 GetThumbs 이벤트 발생. 
override func viewDidAppear(_ animated: Bool){
  super.viewDidAppear(animated)
  ....
  gx_nagent.prepareStream() //동영상 스트리밍 플레이 시작.....
  ....
}

경기도 고양시 덕양구 삼원로 83, 1030호(원흥동, 광양프런티어밸리6차 지식산업센터) 넥스폴리테크놀러지. | TEL: 031) 963-9035. FAX: 031) 601-8094.
Copyright (C) 2024 Nexpoly Technology Inc. All rights reserved.