소개

PlaynPlay는 미디어 서비스에 필요한 동영상 플레이어 부터 콘텐츠 보안, 통계, 분석 등 각종 기능들을 제공하는 토탈 미디어 솔루션입니다.

PlaynPlay App

• PlaynPlay 앱은 스트리밍 재생, 배속, 구간 반복, 워터마크 등의 다양한 동영상 플레이어 기능, 화면 녹화 차단 및 방지 기능, DRM 콘텐츠를 다운로드 및 관리할 수 있는 기능들을 제공합니다.

• 지원 OS : Windows 7 이상, macOS 11 이상

• 별도 설치 파일로 제공됩니다.

PlaynPlay Console

• PlaynPlay 콘솔 사이트는 PlaynPlay 앱과 연동하여, 사용자 및 세션 통계, 녹화 차단 관리, 디바이스 관리, 재생 통계, 보안 및 워터마크 관리 등 미디어 서비스에 필요한 다양한 기능들을 제공합니다.

PlaynPlay DRM packaging tool

• 미디어 콘텐츠 파일을 DRM 패키징하는 기능을 제공합니다.

PlaynPlay auth server

• 미디어 파일 재생을 위한 라이선스 키를 발급하며, 세션을 관리합니다.

설정

다음과 같은 순서로 설정하시면 됩니다.

1. PlaynPlay Console 세팅

• 발급 받은 계정으로 콘솔 사이트에 로그인합니다.

• 서비스할 App을 생성합니다.

• App Key, App ID를 저장합니다. 이 값들은 미디어 재생을 위한 라이선스 키 발급 요청 시 사용됩니다.

  

2. PlaynPlay DRM 패키징

• 콘솔 사이트에서 DRM 패키징 툴을 다운로드합니다.

  

• 서비스할 미디어 파일들을 DRM 패키징하여 준비합니다. (Non DRM도 서비스 가능)

• 자세한 사용 방법은 여기를 참고하세요.

• 다운로드

  • macOS
    • arm64
    • x86_64
  • Windows
    • x86_64
    • x86
  • Linux
    • aarch64
    • x86_64
    • x86

3. 미디어 업로드

• 발급 받은 계정으로 DRM 패키징한 파일을 미디어 서버(콘솔 사이트를 이용)에 업로드합니다.

Agent 설정

var PLAYNPLAY_CONFIG = {
    "minVersion": "latest" | "1.x.x"
};

참고: 스크립트 추가시 'agent.js'보다 먼저 추가해야합니다.

<script type="text/javascript" src="https://설정 값을 저장한 파일 경로/playnplay_config.js">
<script type="text/javascript" src="https://app.playnplay.com/modules/agent.js">

Agent 실행

플레이어를 실행시켜 DRM 패키징 된 미디어 파일을 재생 및 다운로드 할 수 있습니다.

플레이어 실행 절차는 Windows, macOS, iOS, Android 동일합니다.

playnplay: launch()

playnplay.launch = async (type, mediaItemOrUrl, options)

미디어 아이템이나 미디어 주소를 사용하여 플레이어를 실행시킬 수 있습니다. 이때 사용 목적에 따라 타입을 설정할 수 있습니다.

playnplay: download()

playnplay.download = async (mediaItems)

playnplay: getDeviceInfo()

playnplay.getDeviceInfo = async ()

출력: DeviceInfo

브라우저가 실행되고 있는 장치의 정보를 얻어옵니다.

playnplay: LaunchType

playnplay.LaunchType = {
    Streaming: 'streaming',
    Downloading: 'downloading',
    OpeningPage: 'opening-page'
};

playnplay.launch()를 호출할 때, playnplay.LaunchType.Streaming, playnplay.LaunchType.Downloading 과 같이 타입으로 사용합니다. 사용 예제를 참고하세요.

MediaItem

{
    "url": string | URL, 
    "seekable": boolean | null, 
    "returnUrl": string | URL | null, 
    "startTime": number | StartTime | null,
    "drm": DRM | null, 
    "subtitles": [Subtitle] | null, 
    "metadata": Metadata | null,
    "clipping": Clipping | null,
    "useBookmarkCallback": boolean | null
}

DRM

{
    "appId": string,
    "userId": string,
    "userData": object | null,
    "offlineAccessPeriod": number | null
}

미디어 아이템을 구성할 때, 위와 같은 구성 요소를 포함하는 DRM 설정을 추가할 수 있습니다.

Subtitle

{
    "url": string | URL,
    "language": string | null,
    "label": string | null,
    "mode": "autoSelect" | "show" | "hidden" | null
}

미디어 아이템을 구성할 때, 위와 같은 요소를 포함하는 자막을 추가할 수 있습니다.

StartTime

{
    "value": number,
    "syncedAt": Date | null
}

Metadata

{
    "title": string | null,
    "artworkUrl": string | URL | null,
    "downloadPath": string | null
}

미디어 아이템을 구성할 때, 메타데이터를 추가할 수 있습니다.

Clipping

{
    "startTime": number,
    "endTime": number | null
}

Bookmark

{
    "pos": number,
    "title": string | null
}

미디어 항목을 사용자 지정 시작 및 끝 위치로 잘라냅니다. 미디어 아이템을 구성할 때, 클리핑을 추가할 수 있습니다.

Options

{
    "height": number | null,
    "width": number | null
}

미디어 플레이어의 크기를 설정할 수 있습니다. 사용 예제를 참고하세요.

DeviceInfo

{
    "platform": string,
    "platformVersion": string | null,
    "architecture": string | null,
    "model": string | null
}

사용 예제: 동영상 재생

<script type="text/javascript" src="https://app.playnplay.com/modules/agent.js">
<script type="text/javascript">
    const mediaItem = {
        url: "https://sample.playnplay.com/video/sintel-1280-surround.mp4",
        drm: {
            appId: "1ed493af-5988-65b5-a4ca-6d1c45be663c",
            userId: "test-user",
            userData: {
            }
        },
        metadata: {
            title: "제목입니다."
        }
    };
    playnplay.launch(playnplay.LaunchType.Streaming, mediaItem, { width: 900, height: 600 });
</script>

PlaynPlay SDK for Desktop 연동 가이드

• Overview

본 문서는 데스크톱용 PlaynPlay SDK 연동을 위한 가이드 문서입니다.

사용 방법

• 커스텀 페이지

• 샘플

• 디버깅

커스텀 페이지

playnplay: startService()

playnplay.startService= async (appId, scriptURL, options);

PlaynPlay 보안 서비스를 실행합니다. 개발툴을 사용하려면 반드시 호출해야합니다.

커스텀 페이지와 같은 경로에 'playnplay-service.js'를 생성하고 다음 코드를 추가합니다. (이미 다른 서비스워커를 사용 중이라면 해당 서비스워커에 추가합니다.)

self.importScripts('https://app.playnplay.com/modules/playnplay-service.js');

scriptURL이 커스텀 페이지와 다른 경로에 있을 경우 scope를 지정해야합니다. 자세한 내용을 다음 링크를 참조하세요.

Options

{
    "scope": string | null
}

window: openDevTools()

개발툴을 엽니다.

개발 시 디버깅 용도로만 사용하고 프로덕션 환경에 사용하지 않을 것을 권합니다.

HTMLMediaElement: open()

미디어를 엽니다.

예시

<script>
    const appId = 'xxx-xxx-xxx';
    playnplay.startService(appId, './playnplay-service.js');
    window.addEventListener('keydown', (event) => {
        if (event.key === 'F10' && event.ctrlKey) {
            window.openDevTools();
        }
    });
    document.addEventListener('DOMContentLoaded', () => {
        const video = document.querySelector('#player-container video');
        const mediaItem = {
            url: "https://yourcdn.com/video/1.mp4"
        };
        video.open(mediaItem);
    });
</script>
<body>
    <div id="player-container">
        <video controls playsinline autoplay preload="auto" crossorigin="anonymous"></video>
    </div>
    <script src="https://app.playnplay.com/modules/nplayer/nplayer.js"></script>
    <script>
        const player = new NPlayer('#player-container video');
    </script>
</body>

샘플

• 테스트

  • 재생 및 다운로드

  • 커스텀 페이지

• 다운로드

• 서버 사이드 샘플 다운로드

디버깅

에이전트 안에서 실행되는 커스텀 페이지의 콘솔 로그를 출력하는 디버깅 툴

다운로드

• macOS

  • arm64
  • x86_64

• Windows

  • x86_64
  • x86

PlaynPlay SDK for Android 연동 가이드

안드로이드 SDK 다운로드

안드로이드 SDK 샘플 다운로드

SDK 변경 이력은 여기에서 확인 가능합니다.

설정 방법

안드로이드 스튜디오 기준의 설정 방법입니다.

• 시작하기

• 프로젝트 생성

• 프로젝트 설정

  • build.gradle.kts 수정

  • AndroidManifest.xml 수정

시작하기

이 문서는 안드로이드용 PlaynPlay SDK(이하 안드로이드 SDK) 사용 방법을 안내합니다.

안드로이드 SDK는 API 수준 23(안드로이드 6.0/Marshmallow) 이상을 지원합니다.

안드로이드 SDK는 안드로이드의 Jetpack Media3 라이브러리를 기반으로 제작되었습니다. 따라서 안드로이드 SDK를 통해서 Jetpack Media3에서 제공하는 기능을 그대로 이용할 수 있습니다. 그러나 이 문서는 주로 안드로이드 SDK 설치, 사용 및 활용 방법에 대해 다루고 있기 때문에, Jetpack Media3 라이브러리가 제공하는 기능에 대한 상세 정보는 해당 라이브러리의 공식 문서를 참고하시기 바랍니다.

프로젝트 생성

빈 프로젝트 생성

File > New > New Project 를 선택하여, 빈 프로젝트를 생성합니다.

액티비티 선택

템플릿을 참고하여 사용하고자 하는 액티비티를 선택합니다.

프로젝트 설정 및 생성

Name, Package name, Save location, Minimum SDK 및 Build configuration language를 설정하고, Finish 버튼을 눌러 프로젝트를 생성합니다.

프로젝트 설정

build.gradle.kts 수정

안드로이드 SDK 다운로드

안드로이드 SDK 다운로드

안드로이드 SDK 샘플 다운로드

안드로이드 SDK 추가

안드로이드 SDK가 포함된 디렉토리는 프로젝트 내 어디든 상관없습니다.

dependencies {
	implementation(files("libs/NPlayerSDK-release.aar"))
}

외부 라이브러리 의존성 추가

라이브러리 프로젝트 의존성은 안드로이드 SDK가 업데이트 됨에 따라 변동될 수 있습니다. 업데이트가 될 경우 해당 문서를 통해서 알려드리겠습니다.

dependencies {
    implementation("androidx.media3:media3-ui:1.6.0")
    implementation("androidx.media3:media3-session:1.6.0")
    implementation("androidx.media3:media3-exoplayer-smoothstreaming:1.6.0")
    implementation("androidx.fragment:fragment-ktx:1.8.6")
    implementation("androidx.navigation:navigation-fragment-ktx:2.8.9")
    implementation("androidx.navigation:navigation-compose:2.8.9")
    implementation("androidx.room:room-runtime:2.6.1")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
	implementation("net.java.dev.jna:jna:5.17.0@aar")
    implementation("com.google.android.material:material:1.12.0")
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
}

자바 버전

안드로이드 SDK에서 사용하는 자바 관련 버전은 아래와 같습니다.

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
		sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    kotlinOptions {
 		jvmTarget = "11"
    }
}

AndroidManifest.xml 수정

퍼미션 추가

<manifest xmlns:android="....." >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
</manifest>

다운로드를 위한 브로드캐스트 수신기 선언

<receiver
    android:name="com.newin.nplayer.sdk.DownloadCompleteReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.DOWNLOAD_COMPLETE" />
    </intent-filter>
</receiver>

미디어 및 플레이어 관련 설정 추가

<application>
    <activity
        android:name="com.newin.nplayer.sdk.MediaPlayerActivity"
        android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboardHidden"
        android:exported="false"
        android:launchMode="singleTask"
        android:supportsPictureInPicture="true"
        android:theme="@style/Theme.AppCompat"/>
    <service
        android:name="com.newin.nplayer.sdk.MediaPlaybackService"
        android:exported="false"
        android:foregroundServiceType="mediaPlayback">
        <intent-filter>
            <action android:name="androidx.media3.session.MediaSessionService" />        
        </intent-filter>
    </service>
</application>

사용 방법

패키지 이름 추가

콘솔에 로그인하고 설정 > 애플리케이션으로 이동합니다.

아래 Bundle ID (Package name) 섹션에서 추가 버튼을 클릭합니다.

패키지 이름을 추가합니다.

패키지 이름은 build.gradle.kts 파일 내의 applicationId에서 찾을 수 있습니다.

android {
    defaultConfig {
        applicationId = "com.nplayersdk.sample" // 패키지 이름
    }
}

액티비티 구성

먼저 startMediaPlayerService를 호출하여 서비스를 시작합니다. 여기서 플레이어와 미디어세션을 만들고 DRM 기본 설정을 합니다.

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.media3.common.MediaItem
import com.newin.nplayer.sdk.extensions.presentMediaPlayer
import com.newin.nplayer.sdk.extensions.startMediaPlayerService
import com.newin.nplayer.sdk.withDrmConfiguration

class MainActivity : ComponentActivity() {
	override fun onCreate(savedInstanceState: Bundle?) {
		super.onCreate(savedInstanceState)

        startMediaPlayerService("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx") // App 아이디
	}
}

App 아이디는 콘솔에서 설정 > 애플리케이션 > App ID > 보기를 클릭하여 확인 가능합니다. 복사하여 붙여넣기를 하실 수 있습니다.

미디어 아이템 구성 예제

아래처럼, 미디어 아이템을 구성하고 열 수 있습니다.

import androidx.media3.common.MediaItem
import com.newin.nplayer.sdk.MediaPlayerActivityConfiguration
import com.newin.nplayer.sdk.extensions.presentMediaPlayer
import com.newin.nplayer.sdk.extensions.withDrmConfiguration

Button(
	onClick = { 
		// uri를 입력 받아서 아이템을 만듭니다. 이때, 반드시 DRM 설정을 합니다.
		val mediaItem = MediaItem.fromUri("https://example.com/media.mp4")
			.withDrmConfiguration(
				appId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx", // App 아이디
				userId = "사용자 아이디"
			)

		// 백그라운드 재생을 허용하게 설정합니다.
        val configuration = MediaPlayerActivityConfiguration.defaultConfiguration
        configuration.allowsBackgroundPlayback = true

        // 미디어를 엽니다.
		presentMediaPlayer(mediaItem, configuration)
	}
) {
	Text("Open player")
}

startMediaPlayerService

플레이어와 미디어세션을 만들고 DRM 기본 설정을 합니다.

MediaItem.fromUri

미디어 주소를 파라미터로 입력하여 미디어 아이템을 구성합니다. 파라미터로 받을 수 있는 타입은 아래와 같습니다.

withDrmConfiguration

uri를 입력받아서 미디어 아이템을 만들 때, 반드시 DRM 설정을 합니다. 제공받은 App 아이디와 사용자 아이디(User ID)를 입력하면 됩니다.

presentMediaPlayer

구성을 마친 미디어 아이템을 화면에 재생합니다.

자막을 추가한 예제

Media3에서 제공하는 setSubtitleConfigurations() 사용하여 자막을 추가할 수 있습니다.

val mediaItem = MediaItem.Builder()
	.setUri("https://example.com/video.mp4")
	.setSubtitleConfigurations(
		listOf(
			MediaItem.SubtitleConfiguration.Builder(
				Uri.parse("https://example.com/subtitle.vtt")
			)
			.setMimeType(MimeTypes.TEXT_VTT)
			.setLanguage("en")
            .setSelectionFlags(C.SELECTION_FLAG_DEFAULT)
			.build()
		)
	)
	.build()

Seek 기능을 제한한 예제

미디어 아이템을 구성할 때, setSeekable(false)을 사용하여 Seek 기능을 제한할 수 있습니다.

val mediaItem = MediaItem.Builder()
	.setUri("https://www.example.com/video.mp4")
    .setSeekable(false)
    .build()

MediaPlayer

fun MediaPlayer(context: Context): MediaPlayer

안드로이드 SDK에서 제공하는 MediaPlayer가 아니라, Jetpack Media3에서 제공하는 ExoPlayer를 사용하려면 아래와 같이 사용하면 됩니다. ExoPlayer는 Player를 확장한 클래스로 Jetpack Media3에서 제공합니다.

사용 예제

val mediaPlayer = MediaPlayer(context)
mediaPlayer.load(mediaItem)

커스터마이징하여 만든 플레이어를 바로 등록하여 미디어 플레이어를 사용할 수도 있습니다.

fun MediaPlayer(innerPlayer: Player): MediaPlayer

사용 예제

val mediaPlayer = MediaPlayer(player)
mediaPlayer.load(mediaItem)

주의: 현재 안드로이드 SDK는 MediaPlayer()으로 직접 미디어 플레이어를 구성할 경우, DRM 관련 기능을 지원하지 않습니다. DRM 영상을 사용하려면, presentMediaPlayer()를 하여 플레이어를 구성한 후, getMediaPlayer()를 사용해 주세요.

인터페이스

• DownloadManager.Listener

• EventListener

• MediaPlayer

• Player

DownloadManager.Listener

import com.newin.nplayer.sdk.DownloadManager.Listener

DownloadManager.Listener는 다운로드와 관련된 이벤트 처리를 위한 인터페이스로, 위와 같은 메서드를 제공합니다. 각각 메서드에 대한 설명은 아래 메서드를, 리스너를 추가 하는 방법은 addListener를 참고하시면 됩니다.

메서드

onItemAdded

fun onItemAdded(item: DownloadItem)

다운로드할 아이템이 목록에 추가될 때 처리를 위한 메서드입니다. 아이템을 추가할 때 추가적인 처리가 필요할 경우에 이 메서드를 사용합니다.

onItemRemoved

fun onItemRemoved(item: DownloadItem)

다운로드 목록에서 아이템을 제거할 때 처리를 위한 메서드입니다. 아이템이 제거될 때 추가적인 처리가 필요할 경우에 이 메서드를 사용합니다.

onProgressUpdated

fun onProgressUpdated(item: DownloadItem)

다운로드가 진행되는 매순간을 처리하기 위한 메서드입니다. 아이템 다운로드가 진행됨에 따라 추가적인 처리가 필요할 경우에 이 메서드를 사용합니다.

onStatusChanged

fun onStatusChanged(item: DownloadItem)

다운로드 아이템의 상태가 변경될 때 처리를 위한 메서드입니다. 즉, 다운로드를 완료하였거나, 실패하였을 때 등의 상황에 추가적인 처리가 필요할 경우에 이 메서드를 사용합니다.

MediaPlayer

import com.newin.nplayer.sdk.MediaPlayer

interface MediaPlayer : Player

미디어 플레이어 인터페이스입니다. 활성화된 미디어 플레이어에 접근하는 방법은 getMediaPlayer()를 참고하세요.

정적 속성

ACTION_PLAYBACK_FINISHED

companion object {
    const val ACTION_PLAYBACK_FINISHED
}

미디어 재생이 끝났을 때 브로드캐스터 수신기에서 사용하기 위한 정적 속성입니다. 브로드캐스터 수신기를 아래처럼 등록하고 해제하시면 됩니다.

private val playbackFinishedReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent) {
        // 미디어 재생 종료 시 처리할 내용
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    ContextCompat.registerReceiver(
        this,
        playbackFinishedReceiver,
        IntentFilter(MediaPlayer.ACTION_PLAYBACK_FINISHED),
        ContextCompat.RECEIVER_EXPORTED,
    )
}

override fun onDestroy() {
    super.onDestroy()
    unregisterReceiver(playbackFinishedReceiver)
}

onReceive의 intent에서 제공하는 정보는 다음과 같습니다.

속성

allowsPictureInPicturePlayback

var allowsPictureInPicturePlayback: Boolean

allowsCellularAccess

var allowsCellularAccess: Boolean

동영상을 재생(스트리밍)할 때, 셀룰러 데이터를 사용할 지 여부를 나타내는 속성입니다.

audioTracks

val audioTracks: List<Track>

현재 재생 중인 미디어의 오디오 트랙을 가져오는 속성입니다.

autoplay

var autoplay: Boolean

미디어가 중단되지 않고 충분한 양의 미디어 사용이 가능할 때 즉시 재생이 시작되어야 하는지를 나타내는 속성입니다. true면 자동 재생합니다.

buffered

val buffered: TimeRanges

버퍼에 있는 미디어 리소스의 구간을 반환합니다.

currentMediaItem

val currentMediaItem: MediaItem

현재 재생 중인 미디어 아이템을 의미하는 속성입니다.

currentMediaItemIndex

val currentMediaItemIndex: Int

현재 재생 중인 미디어 아이템의 index를 의미하는 속성입니다.

currentSrc

val currentSrc: Uri?

미디어 리소스의 uri를 의미하는 속성입니다.

currentTime

var currentTime: Duration

현재 재생 위치를 Duration 단위로 지정합니다.

currentWatermarkSettings

val currentWatermarkSettings: WatermarkSettings?

현재 워터마크 설정 상태를 반환하는 속성입니다.

defaultMuted

var defaultMuted: Boolean

오디오의 음소거 기본 설정을 나타내는 속성입니다.

defaultPlaybackRate

var defaultPlaybackRate: Float

미디어의 기본 재생 속도를 나타내는 속성입니다.

deviceVolume

var deviceVolume: Float

현재 미디어 플레이어의 음량을 나타내는 속성입니다.

duration

val duration: Duration

현재 미디어 길이를 나타냅니다.

ended

val ended: Boolean

미디어 재생 완료 여부를 나타내는 속성입니다.

error

val error: PlaybackException?

최근 발생한 에러를 나타내는 속성입니다.

isCaptureAllowed

val isCaptureAllowed: Boolean

isSeekable

val isSeekable: Boolean

현재 플레이어에서 Seek 기능을 사용할 수 있는지 여부를 반환하는 속성입니다.

isScrubbing

val isScrubbing: Boolean

loop

var loop: Boolean

미디어 재생이 끝났을 때 다시 처음부터 재생할 지 여부를 나타내는 속성입니다.

mediaItems

val mediaItems: List<MediaItem>

미디어 아이템들의 목록을 나타내는 속성입니다. 해당 속성은 설정이 불가능합니다. 목록 전체를 바꾸고 싶을 때는 Player의 setMediaItems()를 사용하시면 됩니다.

muted

var muted: Boolean

음소거 여부를 나타내는 속성입니다. 음소거면 true, 아니면 false입니다.

paused

val paused: Boolean

미디어가 일시 정지 상태인지 나타내는 속성입니다. 다음과 같은 조건 중 하나라도 해당할 때, true를 반환합니다.

1. playWhenReady의 값이 false일 때,
2. playbackState가 STATE_IDLE일 때 (제한된 리소스를 가지고 있을 때),
3. playbackState가 STATE_ENDED일 때 (미디어 재생이 끝났을 때).

playbackRate

var playbackRate: Float

미디어가 재생 속도를 나타내는 속성입니다. 정상 속도는 1.0이고, 1보다 작을 때는 느리게, 1보다 클 때는 빠르게 재생합니다. 이 때, 오디오 피치 유지 여부는 preservesPitch의 값으로 제어할 수 있습니다.

preservesPitch

var preservesPitch: Boolean

재생 속도에 따른 오디오 피치 유지 여부를 나타내는 속성입니다. 값이 true면 재생 속도가 변해도 오디오 피치는 변함 없으며, false일 경우 재생 속도에 따라 오디오 피치가 변합니다.

repeatRange

var repeatRange: RepeatRange?

반복 구간 범위를 나타내는 속성입니다. null이 아닌 값으로 설정을 했을 경우 해당 구간을 지속해서 반복 재생합니다. start가 설정되어 있지 않을 경우에는 반복 구간의 시작은 미디어의 맨 앞부분이며, end가 설정되어 있지 않을 경우에는 반복 구간의 끝은 미디어의 맨 마지막 부분으로 간주합니다.

screenBrightness

var screenBrightness: Float

seekBackIncrement

var seekBackIncrement: Duration

seekBack()을 호출하여 이동할 때, 현재 위치에서 전으로 이동하는 시간 정도를 나타내는 속성입니다. 왼쪽 방향키를 입력 받거나 하단 인터페이스의 되감기 버튼을 클릭했을 때 이 속성을 사용합니다.

seekForwardIncrement

var seekForwardIncrement: Duration

seekForward()을 호출하여 이동할 때, 현재 위치에서 후로 이동하는 시간 정도를 나타내는 속성입니다. 오른쪽 방향키를 입력 받거나 하단 인터페이스의 빨리 감기 버튼을 클릭했을 때 이 속성을 사용합니다.

seeking

val seeking: Boolean

미디어가 탐색 중이지를 나타내는 속성입니다. 현재 미디어가 새로운 위치로 이동하고 있거나 탐색중이면 true를 반환합니다.

subtitleTracks

val subtitleTracks: List<Track>

현재 재생 중인 미디어의 자막 트랙을 가져오는 속성입니다.

videoTracks

val videoTracks: List<Track>

현재 재생 중인 미디어의 비디오 트랙을 가져오는 속성입니다.

메서드

beginSeekTo

fun beginSeekTo(direction: SeekDirection)

deselectTrack

fun deselectTrack(track: Track)

트랙 선택을 해제하여 비활성화하는 메서드입니다. 자막 트랙만 해제 가능합니다.

endSeekTo

fun endSeekTo(direction: SeekDirection)

enterPictureInPicture

fun enterPictureInPicture(activity: Activity, sourceRectHint: Rect? = null)

fun enterPictureInPicture(activity: Activity, sourceView: View? = null)

화면 속 화면 모드로 전환하는 메서드입니다.

fastSeek

fun fastSeek(to: Duration)

입력된 시간으로 바로 이동하기 위한 메서드입니다.

• 주의: 해당 메서드의 원래 목적은 정확한 위치보다는 새로운 위치에서 더 빠르게 재생을 하도록 하는 것이었습니다. 그러나 안드로이드에서는 현재 정확한 위치와 빠른 재생을 동시에 수행할 수 없기 때문에, 현재는 currentTime, seekTo()를 사용한 것과 유사한 결과를 얻게 됩니다. 즉, 이 메서드를 사용하면 정확한 위치로 이동하게 됩니다. 향후 안드로이드에서 이러한 기능을 제공할 경우, 원래 목적에 맞게 업데이트될 예정입니다.

load

fun load(uri: String)

미디어 주소를 문자열로 입력 받아서 미디어를 로드하기 위한 메서드입니다.

load

fun load(uri: Uri)

미디어 주소를 Uri 타입으로 입력 받아서 미디어를 로드하기 위한 메서드입니다.

load

fun load(mediaItem: MediaItem)

미디어 아이템을 로드하기 위한 메서드입니다.

load

fun load(mediaItems: List<MediaItem>)

미디어 아이템 목록을 로드하기 위한 메서드입니다.

pause

fun pause()

미디어를 일시 정지하기 위한 메서드입니다.

play

fun play()

미디어를 재생하기 위한 메서드입니다.

prepare

fun prepare()

미디어 관련 기본 설정을 하기 위한 메서드입니다. 이 메서드를 실행하면, defaultPlaybackRate, defaultMuted 설정을 미디어 플레이어에 적용하고, 미디어를 로딩하기 시작하고 재생에 필요한 리소스를 확보합니다.

release

fun release()

미디어 목록, 이벤트 핸들러, 리스너 등 미디어에 관련하여 설정했던 것들을 모두 해제한 후, 미디어 플레이어를 릴리스 시키기 위한 메서드입니다. 미디어 플레이어를 더이상 사용하지 않을 시에는 반드시 사용해야 합니다.

seekBack

fun seekBack()

현재 위치에서 속성 seekBackIncrement 만큼 전으로 이동하기 위한 메서드입니다.

seekBack

fun seekBack(increment: Duration)

현재 위치에서 입력된 시간 전으로 이동하기 위한 메서드입니다.

seekForward

fun seekForward()

현재 위치에서 속성 seekForwardIncrement 만큼 후로 이동하기 위한 메서드입니다.

seekForward

fun seekForward(increment: Duration)

현재 위치에서 입력된 시간 후로 이동하기 위한 메서드입니다.

seekTo

fun seekTo(position: Duration, force: Boolean = false)

입력된 시간 위치로 이동하기 위한 메서드입니다.

selectTrack

fun selectTrack(track: Track)

트랙을 선택하여 활성화하는 메서드입니다.

startScrubbing

fun startScrubbing(position: Duration)

stopScrubbing

fun stopScrubbing(position: Duration)

updateScrubbing

fun updateScrubbing(position: Duration)

addEventHandler

fun addEventHandler(handler: EventHandler): EventHandler

이벤트 핸들러를 추가하기 위한 메서드입니다. 반환된 이벤트 핸들러는 이벤트 핸들러를 제거할 목적으로 removeEventHandler()에서 사용할 수 있습니다. 이벤트 핸들러를 추가한 후, 해당 이벤트 핸들러가 더 이상 필요 없을 때는 반드시 removeEventHandler() 메서드를 사용해서 제거하세요.

removeEventHandler

fun removeEventHandler(handler: EventHandler)

addEventHandler()로 추가된 이벤트 핸들러를 제거하기 위한 메서드입니다.

addListener

fun addListener(listener: MediaPlayer.Listener)

이벤트 리스너를 추가하기 위한 메서드입니다. 이벤트 리스너를 추가한 후, 해당 이벤트 리스너가 더 이상 필요 없을 때는 반드시 removeListener() 메서드를 사용해서 제거하세요.

removeListener

fun removeListener(listener: MediaPlayer.Listener)

addListener()로 추가된 이벤트 리스너를 제거하기 위한 메서드입니다.

클래스

RepeatRange

MediaPlayer.RepeatRange에 자세한 설명이 있습니다.

MediaPlayer.Listener

import com.newin.nplayer.sdk.MediaPlayer.Listener

interface MediaPlayer.Listener : Player.Listener

MediaPlayer.Listener는 이벤트 처리를 위한 인터페이스로, 위와 같은 메서드를 제공합니다. 각각 메서드에 대한 설명은 메서드를, 사용 방법은 addListener()를 참고하시면 됩니다. 이벤트 리스너를 추가한 후, 해당 이벤트 리스너가 더 이상 필요 없을 때는 반드시 removeListener() 메서드를 사용해서 제거하세요.
Player에 이미 존재하는 이벤트 리스너일 경우에는, 안드로이드 SDK는 이벤트 핸들러만 제공합니다.
이벤트 리스너를 대신하여 사용 방법에 따라서 이벤트 핸들러를 사용하여 이벤트 처리를 할 수 있습니다. 이벤트 핸들러에서 사용되는 파라미터는 이벤트 리스너의 파라미터와 동일합니다. 이벤트 핸들러의 사용 방법은 addEventHandler()와 클래스를 참고하시면 됩니다.

메서드

onDurationChange

fun onDurationChange(duration: Duration)

미디어의 길이(duration)가 변경될 때 실행합니다.

onEnded

fun onEnded()

재생 목록의 마지막 미디어의 재생이 완료 된 시점에 실행합니다.

onError

fun onError(error: PlaybackException)

에러가 발생하여 리소스를 로드할 수 없을 때 실행합니다.

onLoadedData

fun onLoadedData()

미디어 트랙이 로드되었을 때 실행합니다.

onLoadedMetadata

fun onLoadedMetadata()

메타데이터가 로드되었을 때 실행합니다.

onLoadStart

fun onLoadStart()

미디어 리소스를 로딩하기 시작할 때 실행합니다.

onPause

fun onPause()

미디어 일시 정지를 요청한 후, 일시 정지 상태로 진입하는 시점에 실행합니다.

onPlay

fun onPlay()

미디어가 일시 정지 상태에서 재생 상태로 변경되는 시점에 실행합니다. 단, 재생 위치가 변경될 때는 포함하지 않습니다. 자세한 설명은 EventHandler.Play를 참고하세요.

onPlaybackFinish

fun onPlaybackFinish(mediaItem: MediaItem, position: Duration, duration: Duration?, reason: PlaybackFinishReason)

미디어가 종료될 때 실행합니다. 이 때 마지막 재생 위치(position)와 미디어의 길이(duration) 값을 사용할 수 있습니다. 주의할 점은, 미디어가 로드된 후에 종료할 때만 실행된다는 것입니다. 만약 미디어가 로드되기 전에 종료되는 상황에도 사용하려면, onUnload()를 참고하세요.

onPlaying

fun onPlaying()

재생 위치가 변경되어 재생 되는 것을 포함하여, 미디어가 일시 정지 상태에서 재생 상태로 변경되는 시점에 실행합니다. 자세한 설명은 EventHandler.Playing를 참고하세요.

onPositionDiscontinuity

fun onPositionDiscontinuity(
    player: MediaPlayer,
    oldPosition: Duration,
    newPosition: Duration
)

재생 위치가 변경되는 시점에 실행합니다. 이전 위치와 이동한 위치 모두 접근이 가능합니다.

주의: Player.Listener의 onPositionDiscontinuity()는 이름만 같고, 사용 방법이 다릅니다.

onProgress

fun onProgress()

플레이어가 소스를 읽어오기 시작할 때에 실행합니다.

onRateChange

fun onRateChange(playbackRate: Float)

재생 속도가 변경되는 시점에 실행합니다.

주의: 재생 속도는 그대로이지만, preservesPitch의 값이 변경될 때도 실행 됨

onRepeatRangeChange

fun onRepeatRangeChange(repeatRange: MediaPlayer.RepeatRange?)

구간 반복 모드가 시작되거나 종료되었을 때, 그리고 구간 반복의 시작 위치 또는 종료 위치가 바뀌었을 때 실행합니다.

onSeeked

fun onSeeked()

seek 작업이 완료된 시점, 또는 재생 위치가 변경되는 시점, 또는 seeking 값이 false로 변경되는 시점에 실행합니다.

onSeeking

fun onSeeking()

seek 작업이 시작되는 시점, 또는 seeking 값이 false에서 true로 변경되는 시점에 실행합니다.

onSuspend

fun onSuspend()

미디어 로딩이 중지된 시점에 실행합니다.

onTimeUpdate

fun onTimeUpdate(position: Duration)

currentTime이 변경되는 시점에 실행합니다. 즉, 미디어가 재생이 되는 동안 수행하려는 작업을 이곳에 구현하시면 됩니다.

onUnload

fun onUnload(mediaItem: MediaItem)

미디어가 제거된 시점, 즉, 미디어 주소가 변경되기 직전, 기존에 존재하던 미디어를 비울 때 실행합니다.

onVolumeChange

fun onVolumeChange(volume: Float, muted: Boolean)

볼륨이 변경되는 시점에 실행합니다. 무음(muted) 상태가 변경될 때도 실행합니다.

주의: Player.Listener의 onVolumeChanged() 메서드는 이 이벤트 리스너와 완전히 다른 동작을 합니다. 메서드 이름과 사용하는 파라미터도 다르니 주의하시기 바랍니다.

onWaiting

fun onWaiting()

일시적인 버퍼 부족, 즉 데이터가 충분히 로딩되지 못하거나 데이터가 없어서 재생이 정지된 시점에 실행합니다.

onScrubStart

fun onScrubStart(position: Duration)

| 파라미터 이름 | 타입 | 설명 |
|:--:|:--:|:--:|
|position|[java.time.Duration](https://developer.android.com/reference/java/time/Duration)|스크러빙 위치|

스크러빙이 시작되는 시점에 실행합니다.

## onScrubMove

```kotlin
fun onScrubMove(position: Duration)

| 파라미터 이름 | 타입 | 설명 |
|:--:|:--:|:--:|
|position|[java.time.Duration](https://developer.android.com/reference/java/time/Duration)|스크러빙 위치|

스크러빙 위치가 갱신되는 시점에 실행합니다.

## onScrubMove

```kotlin
fun onScrubStop(position: Duration)

| 파라미터 이름 | 타입 | 설명 |
|:--:|:--:|:--:|
|position|[java.time.Duration](https://developer.android.com/reference/java/time/Duration)|스크러빙 위치|

스크러빙이 종료되는 시점에 실행합니다.

클래스

• AudioTrack

• BookmarkItem

• Context

• DownloadItem

• DownloadItem.Progress

• DownloadManager

• EventHandler

• File

• MediaItem

• MediaItem.Builder

• MediaItem.DrmConfiguration

• MediaMetadata

• MediaPlayer.RepeatRange
  

• MediaPlayerActivityConfiguration

• MediaPlayerActivityConfiguration.SubtitleTextSize

• MediaPlayerControlView

• MediaPlayerException

• MediaPlayerInfoView

• PlaybackInfo

• PlaybackInfoRepository

• SubtitleTrack

• TimeRange

• TimeRanges

• Track

• Uri

• VideoTrack

• WatermarkSettings

AudioTrack

import com.newin.nplayer.sdk.extensions.AudioTrack

class AudioTrack : Track

Track 클래스를 확장한 클래스로, 오디오 트랙에 사용되는 클래스입니다.

BookmarkItem

import com.newin.nplayer.sdk.BookmarkItem

data class BookmarkItem

북마크 아이템을 나타내는 구조체입니다. 북마크 타이틀과 재생 위치의 정보를 가지고 있습니다.

속성

title

val title: String?

position

val position: Duration

Context

import android.content.Context

abstract class Context

Context 클랙스를 확장하여, 미디어 플레이어를 설정하고 사용하는 메서드를 제공합니다.

메서드

getMediaPlayer

fun Context.getMediaPlayer(block: (MediaPlayer) -> Unit)

현재 화면에 있는 플레이어를 제어하고 싶을 때 사용하는 메서드입니다. 미디어 플레이어를 비동기 방식으로 가지고 오기 때문에, 주의해서 사용해 주세요. 미디어 플레이어 사용 후에는 반드시 release()를 호출해주세요.

presentMediaPlayer

미디어를 여는 메서드입니다. 여러 타입을 파라미터로 받을 수 있습니다. 미디어 플레이어를 사용한 후에는 반드시 release()를 호출해주세요.

fun Context.presentMediaPlayer(mediaItem: MediaItem)

fun Context.presentMediaPlayer(
    mediaItem: MediaItem,
    configuration: MediaPlayerActivityConfiguration
)

fun Context.presentMediaPlayer(mediaItems: Collection<MediaItem>)

fun Context.presentMediaPlayer(
    mediaItems: Collection<MediaItem>,
    configuration: MediaPlayerActivityConfiguration
)

fun Context.presentMediaPlayer(
	mediaItems: Collection<MediaItem>,
	startMediaItem: MediaItem
)

fun Context.presentMediaPlayer(
    mediaItems: Collection<MediaItem>,
    startMediaItem: MediaItem,
    configuration: MediaPlayerActivityConfiguration
)

fun Context.presentMediaPlayer(
	mediaItems: Collection<MediaItem>,
	startIndex: Int
)

fun Context.presentMediaPlayer(
    mediaItems: Collection<MediaItem>,
    startIndex: Int,
    configuration: MediaPlayerActivityConfiguration
)

fun Context.presentMediaPlayer(uri: String)

fun Context.presentMediaPlayer(
    uri: String,
    configuration: MediaPlayerActivityConfiguration
)

fun Context.presentMediaPlayer(uri: Uri)

fun Context.presentMediaPlayer(
    uri: Uri,
    configuration: MediaPlayerActivityConfiguration
)

startMediaPlayerService

fun Context.startMediaPlayerService(appId: String)

DownloadItem

import com.newin.nplayer.sdk.DownloadItem

data class DownloadItem

다운로드 아이템을 나타내는 데이터 클래스입니다. 다운로드에 대한 정보, 진행 상태 등의 정보를 가지고 있습니다.

속성

id

val id: DownloadItemId

다운로드 아이템의 고유의 아이디입니다. 다운로드를 일시정지하거나, 다시 시작할 때, 삭제할 때 등에 사용됩니다. 이때, Id는 value class로 아래와 같습니다.

typealias DownloadItemId = UUID

displayPath

val displayPath: String

fromUri

val fromUri: Uri

다운로드할 아이템의 주소입니다.

toUri

val toUri: Uri

다운로드된 아이템이 저장되는 절대 경로입니다.

status

val status: Status

progress

val progress: Progress?

failedReason

val failedReason: FailedReason?

클래스

Status

enum class Status(val value: String)

다운로드 아이템의 상태를 나타내는 열거형 클래스입니다.

Progerss

data class Progress(val downloadedSize: Long, val fileSize: Long)

다운로드 진행 정도를 나타내는 데이터 클래스입니다.

FailedReason

enum class FailedReason(val value: Int)

다운로드가 실패한 이유를 나타내는 열거형 클래스입니다.

Progress

import com.newin.nplayer.sdk.DownloadItem.Progress

data class Progress

다운로드 진행 정도를 나타내는 데이터 클래스입니다. 현재 다운로드된 파일 크기와 전체 파일 크기를 가지고 있습니다.

속성

downloadedSize

val downloadedSize: Long

현재까지 다운로드된 파일의 크기를 나타내는 속성입니다. 단위는 바이트입니다.

fileSize

val fileSize: Long

파일 전체 크기를 나타내는 속성입니다. 단위는 바이트입니다.

DownloadManager

다운로드 매니저를 사용하기 전에 AndroidManifest.xml에 브로드캐스트 수신기를 선언합니다.

<receiver
    android:name="com.newin.nplayer.sdk.DownloadCompleteReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.DOWNLOAD_COMPLETE" />
    </intent-filter>
</receiver>

import com.newin.nplayer.sdk.DownloadManager

class DownloadManager

다운로드 매니저 클래스는 아래와 같은 속성과 메서드를 가지고 있습니다.

정적 속성

shared

companion object {
    val shared: DownloadManager
}

다운로드 매니저에 접근하기 위한 정적 속성입니다. 아래에 언급되는 속성 및 메서드를 호출할 때, DownloadManager.shared를 사용하여 접근할 수 있습니다.

인터페이스

DownloadManager.Listener

interface Listener {
    fun onItemAdded(item: DownloadItem) {}
    fun onItemRemoved(item: DownloadItem) {}
    fun onStatusChanged(item: DownloadItem) {}
    fun onProgressUpdated(item: DownloadItem) {}
}

다운로드와 관련된 이벤트 처리를 위한 인터페이스입니다. 자세한 내용은 DownloadManager.Listener를 참고하세요.

속성

downloadsUri

var downloadsUri: Uri

다운로드된 아이템이 저장되는 디렉토리 중 최상위 디렉토리를 나타내는 속성입니다.

items

val items: List<DownloadItem>

현재 다운로드 목록에 있는 아이템들을 반환하는 속성입니다.

maxParallelDownloads

var maxParallelDownloads: Int

동시에 받을 수 있는 아이템의 최대 개수를 반환하거나 설정합니다.

메서드

add

fun add(mediaItem: MediaItem, allowsCellularAccess: Boolean = true): DownloadItemId

다운로드를 할 미디어 아이템을 추가합니다. 현재 다운로드가 진행되고 있는 아이템의 수가 maxParallelDownloads 보다 적으면 바로 다운로드를 시작합니다. 셀룰러 데이터 사용을 허용하지 않으려면, allowsCellularAccess를 false로 설정하여 호출하십시오.

getItemsByStatus

fun getItemsByStatus(status: DownloadItem.Status): List<DownloadItem>

특정 다운로드 상태의 아이템 목록을 가져오기 위해서 사용하는 메서드입니다.

pause

fun pause(id: DownloadItemId)

다운로드를 일시 정지할 때 사용하는 메서드입니다.

pauseAll

fun pauseAll()

다운로드 목록에 있는 모든 아이템의 다운로드를 일시 정지하게 하는 메서드입니다.

remove

fun remove(id: DownloadItemId)

다운로드 목록에서 아이템을 지울 때 사용하는 메서드입니다.

removeAll

fun removeAll()

다운로드 아이템 목록을 모두 지우는 메서드입니다.

removeCompleted

fun removeCompleted()

다운로드가 완료된 아이템을 목록에서 모두 지우는 메서드입니다.

resume

fun resume(id: DownloadItemId)

다운로드를 일시 정지한 아이템의 다운로드를 재개하는 메서드입니다.

resumeAll

fun resumeAll()

일시 정지한 모든 아이템의 다운로드를 재개하는 메서드입니다.

addListener

fun addListener(listener: Listener)

다운로드 매니저 리스너를 추가하기 위한 메서드입니다. 리스너를 추가한 후, 해당 리스너가 더 이상 필요 없을 때는 반드시 removeListener() 메서드를 사용해서 제거하세요.

removeListener

fun removeListener(listener: Listener)

다운로드 매니저 리스너를 제거하기 위한 메서드입니다.

이벤트 핸들러

import com.newin.nplayer.sdk.EventHandler

sealed class EventHandler

이벤트 핸들러의 종류와 사용 방법에 대한 설명입니다. 각각 데이터 클래스에 대한 설명은 클래스를, 사용 방법은 addEventHandler()를 참고하시면 됩니다. 이벤트 핸들러를 추가한 후, 해당 이벤트 핸들러가 더 이상 필요 없을 때는 반드시 removeEventHandler() 메서드를 사용해서 제거하세요.
이벤트 핸들러를 대신하여 사용 방법에 따라서 이벤트 리스너를 사용하여 이벤트 처리를 할 수 있습니다. 이벤트 리스너에서 사용되는 파라미터는 이벤트 핸들러의 파라미터와 동일합니다. 이벤트 리스너의 사용 방법은 addEventListener()와 메서드를 참고하시면 됩니다.

클래스

DurationChange

data class DurationChange(val listener: (Duration) -> Unit) : EventHandler()

미디어의 길이(duration)가 변경되었을 때를 처리하기 위한 핸들러입니다.

Ended

data class Ended(val listener: () -> Unit) : EventHandler()

재생 목록의 마지막 미디어의 재생이 완료 된 시점에 사용하기 위한 핸들러입니다.

Error

data class Error(val listener: (PlaybackException) -> Unit) : EventHandler()

에러가 발생하여 리소스를 로드할 수 없을 때 사용하기 위한 핸들러입니다.

LoadedData

data class LoadedData(val listener: () -> Unit) : EventHandler()

미디어 트랙이 로드되었을 때 사용하기 위한 핸들러입니다.

LoadedMetadata

data class LoadedMetadata(val listener: () -> Unit) : EventHandler()

메타데이터가 로드되었을 때 사용하기 위한 핸들러입니다.

LoadStart

data class LoadStart(val listener: () -> Unit) : EventHandler()

미디어 리소스를 로딩하기 시작할 때 사용하기 위한 핸들러입니다.

MediaItemTransition

data class MediaItemTransition(val listener: (MediaItem?, @Player.MediaItemTransitionReason Int) -> Unit) : EventHandler()

미디어 아이템이 교체 되는 시점에 사용하기 위한 핸들러입니다.
참고: 이벤트 리스너는 Player.Listener에서 제공하는 것을 사용하시면 됩니다.

Pause

data class Pause(val listener: () -> Unit) : EventHandler()

미디어 일시 정지를 요청한 후, 일시 정지 상태로 진입하는 시점에 사용하기 위한 핸들러입니다.

Play

data class Play(val listener: () -> Unit) : EventHandler()

미디어가 일시 정지 상태에서 재생 상태로 변경되는 시점에 사용하기 위한 핸들러입니다. 단, 재생 위치가 변경될 때는 포함하지 않습니다.

사용자가 재생 버튼을 클릭하거나 mediaPlayer.play()를 호출하는 등 플레이어에 재생 명령을 내렸을 때 처럼 직접 명령을 했을 때 상황에서 이벤트 처리를 여기서 할 수 있음 EventHandler.Playing과 다른 점은 seekTo() 등을 통해 재생 위치가 변경될 때의 이벤트는 여기서 처리할 수 없다는 것입니다. 중요한 점이 하나 더 있는데, Play와 관련된 이벤트 핸들러가 호출되면, Playing 이벤트는 Play 이벤트 이 후에 언제나 호출됩니다.

PlaybackFinish

data class PlaybackFinish(val listener: (MediaItem, Duration, Duration?, PlaybackFinishReason) -> Unit) : EventHandler()

미디어가 종료될 때 사용하기 위한 핸들러입니다. 이 때 마지막 재생 위치(position)와 미디어의 길이(duration) 값을 사용할 수 있습니다. 주의할 점은, 미디어가 로드된 후에 종료될 때만 사용할 수 있다는 것입니다. 만약 미디어가 로드되기 전에 종료되는 상황에도 사용하려면, Unload를 참고하세요.

PlaybackStateChange

data class PlaybackStateChange(val listener: (@Player.State Int) -> Unit) : EventHandler()

미디어 로딩 상태에 따른 처리, 즉, 버퍼링인지 준비가 된 상태인지, 끝이 났는지, 플레이어를 종료하였는지 등의 상황에 따라 처리하기 위한 핸들러입니다.
참고: 이벤트 리스너는 Player.Listener에서 제공하는 것을 사용하시면 됩니다.

Playing

data class Playing(val listener: () -> Unit) : EventHandler()

재생 위치가 변경되어 재생 되는 것을 포함하여, 미디어가 일시 정지 상태에서 재생 상태로 변경되는 시점에 사용하기 위한 핸들러입니다.

즉, seekBack(), seekForward(), seekTo() 등의 호출로 재생 위치가 변경되기 위해, 미디어가 잠시 멈추었다가 다시 재생되는 이벤트를 처리할 수 있다는 것이 EventHandler.Play와 다른 점입니다. Playing과 관련된 이벤트 핸들러는 Play 이벤트 이후에 호출됩니다.

PositionDiscontinuity

data class PositionDiscontinuity(
    val listener: (MediaPlayer, Duration, Duration) -> Unit
) : EventHandler()

재생 위치가 변경되는 시점에 사용하기 위한 핸들러입니다. 이전 위치와 이동한 위치 모두 접근이 가능합니다.

Progress

data class Progress(val listener: () -> Unit) : EventHandler()

플레이어가 소스를 읽어오기 시작할 때에 사용하기 위한 핸들러입니다.

RateChange

data class RateChange(val listener: (Float) -> Unit) : EventHandler()

재생 속도가 변경되는 시점에 사용하기 위한 핸들러입니다. 주의: 재생 속도는 그대로이지만, preservesPitch의 값이 변경될 때도 호출 됨

RepeatModeChange

data class RepeatModeChange(val listener: (@Player.RepeatMode Int) -> Unit) : EventHandler()

반복 모드가 변경되는 시점에 사용하기 위한 핸들러입니다.
참고: 이벤트 리스너는 Player.Listener에서 제공하는 것을 사용하시면 됩니다.

RepeatRangeChange

data class RepeatRangeChange(val listener: (MediaPlayer.RepeatRange?) -> Unit) : EventHandler()

구간 반복 모드가 시작되거나 종료되었을 때, 그리고 구간 반복의 시작 위치 또는 종료 위치가 바뀌었을 때를 처리하기 위한 핸들러입니다.

Seeked

data class Seeked(val listener: () -> Unit) : EventHandler()

seek 작업이 완료된 시점, 또는 재생 위치가 변경되는 시점, 또는 seeking 값이 false로 변경되는 시점에 사용하기 위한 핸들러입니다.

Seeking

data class Seeking(val listener: () -> Unit) : EventHandler()

seek 작업이 시작되는 시점, 또는 seeking 값이 false에서 true로 변경되는 시점에 사용하기 위한 핸들러입니다.

Suspend

data class Suspend(val listener: () -> Unit) : EventHandler()

미디어 로딩이 중지된 시점에 사용하기 위한 핸들러입니다.

TimeUpdate

data class TimeUpdate(val listener: (Duration) -> Unit) : EventHandler()

currentTime이 변경되는 시점에 사용하기 위한 핸들러입니다. 즉, 미디어가 재생이 되는 동안 수행하려는 작업을 이곳에 구현하시면 됩니다.

Unload

data class Unload(val listener: (MediaItem) -> Unit) : EventHandler()

미디어가 제거된 시점, 즉, 미디어 주소가 변경되기 직전, 기존에 존재하던 미디어를 비울 때를 처리하기 위한 핸들러입니다.

VideoSizeChange

data class VideoSizeChange(val listener: (VideoSize) -> Unit) : EventHandler()

영상 크기가 바뀌는 시점에 사용하기 위한 핸들러입니다. 다음 영상으로 이동할 때, 영상 크기가 0x0으로 바뀌었다가 다음 영상의 크기로 바뀌게 되는데, 0x0으로 바뀔 때도 해당 이벤트는 호출됩니다. 즉, 다음 영상으로 이동할 경우, 이 핸들러는 두 번 호출 됩니다.
참고: 이벤트 리스너는 Player.Listener에서 제공하는 것을 사용하시면 됩니다.

VolumeChange

data class VolumeChange(val listener: (Float, Boolean) -> Unit) : EventHandler()

볼륨이 변경되는 시점에 사용하기 위한 핸들러입니다. 무음(muted) 상태가 변경될 때도 호출됩니다.

주의: Player.Listener의 onVolumeChanged() 메서드는 이 핸들러와 전혀 다릅니다. 메서드 이름과 사용하는 파라미터도 다르니 주의하시기 바랍니다.

Waiting

data class Waiting(val listener: () -> Unit) : EventHandler()

일시적인 버퍼 부족, 즉 데이터가 충분히 로딩되지 못하거나 데이터가 없어서 재생이 정지된 시점에 사용하기 위한 핸들러입니다.

FragmentManager

import androidx.fragment.app.FragmentManager

androidx.fragment.app.FragmentManager 클래스를 확장하여, MediaPlayerBaseFragment의 미디어를 로드할 수 있는 기능을 제공합니다.

메소드

load

fun FragmentManager.load(parameters: MediaPlayerBaseFragment.Parameters) 

MediaItem

import androidx.media3.common.MediaItem

미디어 아이템의 정보를 가져올 수 있는 위의 속성 및 메서드를 제공합니다. Agent에서 설정한 값을 불러올 수 있습니다.

속성

disablePlaybackRate

val MediaItem.disablePlaybackRate: Boolean

미디어의 배속 기능 허용 여부를 나타내는 속성입니다.

returnUrl

val MediaItem.returnUrl: Uri?

Agent에서 설정한 미디어 아이템의 리턴 Url입니다.

seekable

val MediaItem.seekable: Boolean

미디어의 Seek 기능 허용 여부를 나타내는 속성입니다.

title

val MediaItem.title: CharSequence?

미디어 메타 데이터에 저장된 제목을 가져오는 속성입니다. 만약 미디어 메타 데이터에 제목이 없다면, 파일 이름을 가져옵니다.

uri

val MediaItem.uri: Uri?

미디어 아이템에 따라 로컬 주소가 나올 수도 있고, 웹 주소도 나올 수 있습니다.

useBookmarkCallback

val MediaItem.useBookmarkCallback: Boolean

메서드

withDrmConfiguration

import com.newin.nplayer.sdk.extensions.withDrmConfiguration

fun MediaItem.withDrmConfiguration(
    appId: String,
    userId: String,
    userData: Map<String, Any> = emptyMap(),
    offlineAccessPeriod: Duration? = null,
): MediaItem

App 아이디와 사용자 아이디를 사용하여 DRM 설정을 하는 메서드입니다. Callback URL에 전달할 데이터(사용자 데이터)와 오프라인 재생 기한 설정을 추가하여 DRM 설정을 할 수 있습니다.

MediaItem.Builder

import androidx.media3.common.MediaItem.Builder

MediaItem.Builder 클래스를 확장하여, Seek 기능에 대한 메서드를 제공합니다.

메서드

setDisablePlaybackRate

fun MediaItem.Builder.setDisablePlaybackRate(disablePlaybackRate: Boolean): MediaItem.Builder

미디어 아이템의 배속 기능을 허용할 지에 대한 여부를 설정하는 메서드입니다.

setSeekable

fun MediaItem.Builder.setSeekable(seekable: Boolean): MediaItem.Builder

미디어 아이템의 Seek 기능을 허용할 지에 대한 여부를 설정하는 메서드입니다.

setUseBookmarkCallback

fun MediaItem.Builder.setUseBookmarkCallback(useBookmarkCallback: Boolean): MediaItem.Builder

MediaItem.DrmConfiguration

import androidx.media3.common.MediaItem.DrmConfiguration

DRM 설정에 포함된 App 아이디, 사용자 아이디, 오프라인 재생 기간을 가져올 수 있는 속성을 제공합니다.

미디어 아이템의 아래 해당하는 속성에 접근하기 위해서는 아래 자바 코드(androidx.media3.common.MediaItem.java)를 참고하시면 됩니다.

public final class MediaItem implements Bundleable {
    @Nullable public final LocalConfiguration localConfiguration;
}

public static final class LocalConfiguration implements Bundleable {
    @Nullable public final DrmConfiguration drmConfiguration;
}

속성

appId

import com.newin.nplayer.sdk.extensions.appId

val MediaItem.DrmConfiguration.appId: String?

App 아이디를 가져오는 속성입니다.

offlineAccessPeriod

import com.newin.nplayer.sdk.extensions.offlineAccessPeriod

val MediaItem.DrmConfiguration.offlineAccessPeriod: Duration?

다운로드 컨텐츠의 오프라인 재생 기간을 가져오는 속성입니다.

userId

val MediaItem.DrmConfiguration.userId: String?

사용자 아이디를 가져오는 속성입니다.

MediaMetadata

import androidx.media3.common.MediaMetadata

미디어 메타 데이터 클래스입니다.

속성

artworkUrl

@Nullable Uri artworkUri

미디어 아이템의 아트워크 경로를 나타내는 속성입니다.

title

@Nullable CharSequence title

미디어 아이템의 제목을 나타내는 속성입니다.

메서드

buildUpon()

MediaMetadata.Builder buildUpon()

미디어 메타 데이터를 추가하거나 수정하고자 할 때 사용하는 메서드입니다. 변경 후, .build()를 호출하여 구성을 완료합니다.

정적 클래스

Builder

static class Builder

미디어 메타데이터를 만드는 클래스입니다.

MediaPlayer.RepeatRange

import com.newin.nplayer.sdk.MediaPlayer.RepeatRange

data class RepeatRange(val start: Duration, val end: Duration)

구간 반복에 사용되는 데이터 클래스입니다.

생성자 파라미터

속성

start

val start: Duration

end

val end: Duration

메서드

withStart

fun withStart(start: Duration): RepeatRange

withEnd

fun withEnd(end: Duration): RepeatRange

MediaPlayerActivityConfiguration

import com.newin.nplayer.sdk.MediaPlayerActivityConfiguration

data class MediaPlayerActivityConfiguration(
    var allowsBackgroundPlayback: Boolean,
    var allowsCellularAccess: Boolean,
    var allowsPictureInPicturePlayback: Boolean,
    var controllerShowTimeout: Duration,
    var defaultPlaybackRate: Float,
    var seekBackwardIncrement: Duration,
    var seekForwardIncrement: Duration,
    var screenOrientationLock: ScreenOrientationLock,
    var subtitleDisplayPosition: SubtitleDisplayPosition,
    var subtitleTextPosition: Float,
    var subtitleTextSize: SubtitleTextSize,
)

미디어 플레이어의 설정을 도와주는 데이터 클래스입니다. 아래와 같은 생성자 파라미터 및 속성, 열거형을 가지고 있습니다. configuration은 presentMediaPlayer()를 호출할 때 사용하여 미디어 플레이어를 설정합니다.

생성자 파라미터

정적 속성

defaultConfiguration

companion object {
    val defaultConfiguration: MediaPlayerActivityConfiguration
}

기본 설정 값을 가져오는 정적 속성입니다. MediaPlayerActivityConfiguration.defaultConfiguration 를 사용하여 기본 설정 값을 가져올 수 있습니다.

속성

allowsBackgroundPlayback

var allowsBackgroundPlayback: Boolean = false

백그라운드 재생을 허용할 지 여부를 나타내는 속성입니다.

allowsCellularAccess

var allowsCellularAccess: Boolean = true

미디어를 재생할 때, 셀룰러 데이터를 사용할 지 여부를 나타내는 속성입니다.

allowsPictureInPicturePlayback

var allowsPictureInPicturePlayback: Boolean = true

화면 속 화면 모드를 허용할 지 여부를 나타내는 속성입니다.

controllerShowTimeout

var controllerShowTimeout: Duration = Duration.ofSeconds(5)

해당 시간만큼 아무 것도 입력하지 않으면 컨트롤러가 사라집니다. 0초로 설정할 경우에는 컨트롤러를 자동으로 숨기지 않습니다.

defaultPlaybackRate

var defaultPlaybackRate: Float = 1f

미디어 재생 속도를 나타내는 속성입니다.

seekBackwardIncrement

var seekBackwardIncrement: Duration = Duration.ofSeconds(10)

현재 위치에서 전으로 탐색하는 시간을 나타내는 속성입니다.

seekForwardIncrement

var seekForwardIncrement: Duration = Duration.ofSeconds(10)

현재 위치에서 후로 탐색하는 시간을 나타내는 속성입니다.

screenOrientationLock

var screenOrientationLock: ScreenOrientationLock = ScreenOrientationLock.Off

화면의 고정 상태를 나타내는 속성입니다.

subtitleDisplayPosition

var subtitleDisplayPosition: SubtitleDisplayPosition = SubtitleDisplayPosition.OnVideo

자막 추력 위치를 나타내는 속성입니다.

subtitleTextPosition

var subtitleTextPosition: Float = 1f

자막 위치를 나타내는 속성입니다. 이 속성은 화면에서 자막이 배치될 위치를 비율로 표현하며, 값의 범위는 0f에서 1f 사이입니다. 기본값은 1f으로, 자막이 화면의 맨 아래에 위치함을 의미합니다.

subtitleTextSize

var subtitleTextSize: SubtitleTextSize = SubtitleTextSize.Pixel(32)

자막 크기를 나타내는 속성입니다. 자막 크기를 픽셀 단위 또는 비율로 나타낼 수 있습니다.

클래스

SubtitleTextSize

sealed class SubtitleTextSize

자막 크기를 나타내는 클래스입니다.

열거형

ScreenOrientationLock

enum class ScreenOrientationLock

화면 방향 고정 상태를 나타내는 열거형입니다.

SubtitleDisplayPosition

enum class SubtitleDisplayPosition

자막 출력 위치를 나타내는 열거형입니다.

MediaPlayerActivityConfiguration.SubtitleTextSize

import com.newin.nplayer.sdk.MediaPlayerActivityConfiguration.SubtitleTextSize

sealed class SubtitleTextSize

자막 크기를 나타내는 클래스입니다. 자막 크기를 픽셀 단위 또는 비율로 표현할 수 있습니다.

클래스

Pixel

data class Pixel(val pixel: Float) : SubtitleTextSize()

자막 크기를 픽셀 단위로 설정합니다.

Scale

data class Scale(val scale: Float) : SubtitleTextSize()

자막 크기를 비율로 설정합니다.

MediaPlayerBaseFragment

import com.newin.nplayer.sdk.MediaPlayerBaseFragment

open class MediaPlayerBaseFragment : Fragment()

androidx.fragment.app.Fragment를 상속한 미디어 플레이어 프레그먼의 기반 클래스입니다.

속성

playerView

val playerView: MediaPlayerBaseView

player

val player: MediaPlayer?

parameters

val parameters: MediaPlayerBaseFragment.Parameters

오버라이드 가능한 메서드

onPlayerCreated

override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View

MediaPlayerBaseView를 상속하여 만든 사용자 플레이어 뷰를 제공합니다. 오버라이드하지 않으면 SDK에서 기본으로 제공되는 플레이어 뷰 객체를 만듭니다.

참고: android.android.app.Fragment.onCreateView

onPlayerCreated

open fun onPlayerCreated(player: MediaPlayer)

MediaPlayer 객체가 생성되면 호출됩니다.

onDeviceRootedOrAppPlayerDetected

open fun onDeviceRootedOrAppPlayerDetected()

장치가 루팅되거나 앱 플레이어를 감지기하면 호출됩니다.

MediaPlayerBaseFragment.Parameters

import com.newin.nplayer.sdk.MediaPlayerBaseFragment.Parameters

data class Parameters(
    val mediaItems: List<MediaItem>,
    val startMediaItemIndex: Int = 0,
    val defaultPlaybackRate: Float = 1f,
    val seekBackIncrement: Duration = Duration.ofSeconds(10),
    val seekForwardIncrement: Duration = Duration.ofSeconds(10),
    val allowsCellularAccess: Boolean = true,
    val allowsBackgroundPlayback: Boolean = false,
    val allowsPictureInPicturePlayback: Boolean = true,
    val controllerShowTimeout: Duration = Duration.ofSeconds(5),
    val subtitleDisplayPosition: SubtitleDisplayPosition = SubtitleDisplayPosition.OnVideo,
    val subtitleTextPosition: Float = 1f,
    val subtitleTextSize: SubtitleTextSize = SubtitleTextSize.Pixel(SubtitleTextSize.DEFAULT_FONT_PIXEL_SIZE * 2),
    val extras: Bundle? = null,
)

미디어 플레이어 설정을 담고 있는 구성 객체입니다.

참고: FragmentManager.load

속성

mediaItems

val mediaItems: List<MediaItem>

startMediaItemIndex

val startMediaItemIndex: Int

defaultPlaybackRate

val defaultPlaybackRate: Float

seekBackIncrement

val seekBackIncrement: Duration

seekForwardIncrement

val seekForwardIncrement: Duration

allowsCellularAccess

val allowsCellularAccess: Boolean

allowsBackgroundPlayback

val allowsBackgroundPlayback: Boolean

allowsPictureInPicturePlayback

val allowsPictureInPicturePlayback: Boolean

controllerShowTimeout

val controllerShowTimeout: Duration

subtitleDisplayPosition

val subtitleDisplayPosition: SubtitleDisplayPosition

subtitleTextPosition

val subtitleTextPosition: Float

subtitleTextSize

val subtitleTextSize: SubtitleTextSize

extras

val extras: Bundle?

정적 메소드

fun fromBundle(bundle: Bundle): Parameters

메소드

fun toBundle(): Bundle

MediaPlayerBaseView

import com.newin.nplayer.sdk.MediaPlayerBaseView

open class MediaPlayerBaseView(context: Context) : PlayerView(context)

androidx.media3.ui.PlayerView를 상속한 미디어 플레이어 뷰의 기반 클래스입니다.

속성

player

var player: MediaPlayer?

videoContainerView

val videoContainerView: ViewGroup

controlContainerView

val controlContainerView: ViewGroup

infoContainerView

val infoContainerView: ViewGroup

subtitleTextSize

var subtitleTextSize: SubtitleTextSize

subtitleDisplayPosition

var subtitleDisplayPosition: SubtitleDisplayPosition

subtitleTextFractionPosition

var subtitleTextFractionPosition: Float

subtitleTextFractionPosition

var subtitleTextPixelPosition: Float

videoPan

var videoPan: PointF

videoZoom

var videoZoom: Float

메소드

containsPointInSubtitleTextBounds

fun containsPointInSubtitleTextBounds(point: PointF): Boolean

setAutoHideControl

fun setAutoHideControl()

setSubtitleTextPosition

fun setSubtitleTextPosition(position: SubtitleTextPosition,alignment: SubtitleTextAlignment)

unsetAutoHideControl

fun unsetAutoHideControl()

zoomVideo

fun zoomVideo(scaleFactor: Float, pivotX: Float, pivotY: Float)

zoomVideo

fun zoomVideo(scaleFactor: Float)

오버라이드 가능한 메서드

onAttachedToPlayer

open fun onAttachedToPlayer(player: MediaPlayer)

onDetachedFromPlayer

open fun onDetachedFromPlayer(player: MediaPlayer)

onVideoZoomChange

open fun onVideoZoomChange(scaleFactor: Float)

MediaPlayerException

import com.newin.nplayer.sdk.MediaPlayerException

class MediaPlayerException : PlaybackException

예외 처리를 위한 클래스입니다. androidx.media3.common.PlaybackException을 확장한 클래스로 아래와 같은 예외 처리 클래스로 사용됩니다.

AccessRightsExpiredException

class AccessRightsExpiredException(override val message: String) : MediaPlayerException

접근 권한이 만료된 경우

AppBundleNotRegisteredException

class AppBundleNotRegisteredException : MediaPlayerException

등록되지 않은 앱 번들 아이디를 사용한 경우

DeviceLimitExceededException

class DeviceLimitExceededException(override val message: String) : MediaPlayerException

기기 제한이 초과한 경우

LicenseCheckFailedException

class LicenseCheckFailedException(override val message: String) : MediaPlayerException

라이선스 확인에 실패한 경우

LicenseCheckFailureException

class LicenseCheckFailureException(override val message: String) : MediaPlayerException

라이선스 확인에 실패한 경우

LicenseNotFoundException

class LicenseNotFoundException(override val message: String) : MediaPlayerException

라이선스를 찾을 수 없는 경우

MultipleConnectionsException

class MultipleConnectionsException(override val message: String) : MediaPlayerException

동시 접속이 감지된 경우

NetworkException

class NetworkException(override val message: String) : MediaPlayerException

네트워크 관련 에러가 발생한 경우

NoAccessRightsException

class NoAccessRightsException(override val message: String) : MediaPlayerException

접근 권한이 없는 경우

NoCellularAccessException

class NoCellularAccessException : MediaPlayerException

셀룰러 데이터 사용이 허용되지 않은 상황에서 와이파이 연결이 끊어졌는데 미디어를 재생하려는 경우

NoOfflineAccessRightsException

class NoOfflineAccessRightsException(override val message: String) : MediaPlayerException

오프라인 접근 권한이 없는 경우

OfflineAccessRightsExpiredException

class OfflineAccessRightsExpiredException(override val message: String) : MediaPlayerException

오프라인 접근 권한이 만료된 경우

PlaybackLimitExceededException

class PlaybackLimitExceededException(override val message: String) : MediaPlayerException

재생 제한이 초과된 경우

SessionClosedException

class SessionClosedException(override val message: String) : MediaPlayerException

세션이 종료된 경우

SessionNotFoundException

class SessionNotFoundException(override val message: String) : MediaPlayerException

세션을 찾을 수 없는 경우

UnauthorizedException

class UnauthorizedException(override val message: String) : MediaPlayerException

권한이 없는 경우

UnexpectedException

class UnexpectedException(override val message: String, override val cause: Throwable?) : MediaPlayerException

현재 정의 되지 않은 에러가 발생한 경우

PlaybackInfo

import com.newin.nplayer.sdk.PlaybackInfo

data class PlaybackInfo

재생 정보 저장소에 저장된 정보를 나타내는 데이터 글래스입니다. 재생 정보 저장소의 shared 속성과 findBy 메서드를 사용하여 미디어의 정보를 가져올 수 있습니다.

속성

artworkUri

val artworkUri: Uri?

미디어 아이템의 아트워크 경로를 나타내는 속성입니다.

duration

val duration: Duration?

미디어 아이템의 전체 길이를 나타내는 속성입니다.

expiresOn

val expiresOn: Instant?

미디어 아이템의 만료 일시를 나타내는 속성입니다.

lastPlayedTime

val lastPlayedTime: Duration?

미디어 아이템이 마지막으로 재생한 위치를 나타내는 속성입니다.

uri

val uri: Uri

미디어의 주소를 나타내는 속성입니다. 재생 정보 저장소로부터 정보를 가져올 때, 이 미디어 주소를 사용합니다.

PlaybackInfoRepository

import com.newin.nplayer.sdk.PlaybackInfoRepository

class PlaybackInfoRepository(context: Context)

재생 정보 저장소를 나타내는 클래스입니다. 미디어의 uri를 알고 있으면, 아래처럼, 속성 shared와 메서드 findBy()를 사용하여 해당 uri의 미디어 아이템 정보를 가져올 수 있습니다.

정적 속성

shared

companion object {
    val shared: PlaybackInfoRepository
}

재생 정보 저장소에 접근하기 위한 정적 속성입니다. 아래에 언급되는 메서드를 호출할 때, PlaybackInfoRepository.shared를 사용하여 접근할 수 있습니다.

메서드

findBy

fun findBy(uri: Uri): PlaybackInfo?

SubtitleTrack

import com.newin.nplayer.sdk.extensions.SubtitleTrack

class SubtitleTrack : Track

Track 클래스를 확장한 클래스로, 자막 트랙에 사용되는 클래스입니다.

아래와 같은 MIME type의 자막 트랙에 대해 다중 자막 선택을 지원합니다.

TimeRange

import com.newin.nplayer.sdk.utils.TimeRange

data class TimeRange(val start: Duration, val duration: Duration)

buffered 속성에서 사용되는 데이터 클래스입니다.

생성자 파라미터

TimeRanges

import com.newin.nplayer.sdk.utils.TimeRanges

data class TimeRanges

buffered 속성에서 사용되는 데이터 클래스입니다.

속성

length

val length: Int

메서드

start

fun start(index: Int): Duration

end

fun end(index: Int): Duration

Track

import com.newin.nplayer.sdk.extensions.Track

sealed class Track

AudioTrack, SubtitleTrack, VideoTrack에 사용하기 위한 클래스입니다.

속성

type

val type: @TrackType Int

@interface TrackType {}

static int TRACK_TYPE_AUDIO = 1;
static int TRACK_TYPE_VIDEO = 2;
static int TRACK_TYPE_TEXT = 3;

현재 트랙이 오디오 트랙(1) 인지, 비디오 트랙(2) 인지, 자막 트랙(3) 인지 알려주는 속성입니다.

format

val format: Format

현재 트랙의 format을 나타내는 속성입니다.

isSelected

val isSelected: Boolean

현재 트랙이 선택되었는지 여부를 나타내는 속성입니다.

Uri

import android.net.Uri

android.net.Uri 클래스를 확장하여, Uri를 미디어 아이템으로 만드는 메서드를 제공합니다.

메서드

toMediaItem

fun Uri.toMediaItem(): MediaItem

uri를 미디어 아이템으로 만드는 메서드입니다.

VideoTrack

import com.newin.nplayer.sdk.extensions.VideoTrack

class VideoTrack : Track

Track 클래스를 확장한 클래스로, 비디오 트랙에 사용되는 클래스입니다.

WatermarkSettings

import com.newin.nplayer.sdk.WatermarkSettings

data class WatermarkSettings

워터마크 설정을 나타내는 데이터 클래스입니다.

속성

열거형

WatermarkSettings.Position

import com.newin.nplayer.sdk.WatermarkSettings.Position

워터마크의 위치를 나타내는 열거형입니다.

열거형

• DownloadItem.FailedReason

• DownloadItem.Status

• MediaPlayerActivityConfiguration.ScreenOrientationLock

• MediaPlayerActivityConfiguration.SubtitleDisplayPosition

• PlaybackFinishReason

DownloadItem.FailedReason

import com.newin.nplayer.sdk.DownloadItem.FailedReason

enum class FailedReason

다운로드가 실패한 이유를 나타내는 열거형입니다.

AccessRightsExpired

DownloadItem.FailedReason.AccessRightsExpired

접근 권한이 만료된 경우

CannotResume

DownloadItem.FailedReason.CannotResume

다운로드를 재개할 수 없는 경우

DeviceLimitExceeded

DownloadItem.FailedReason.DeviceLimitExceeded

기기 제한이 초과한 경우

DeviceNotFound

DownloadItem.FailedReason.DeviceNotFound

외부 저장소(SD 카드)가 없는 경우

FileAlreadyExists

DownloadItem.FailedReason.FileAlreadyExists

파일이 이미 존재하는 경우

FileError

DownloadItem.FailedReason.FileError

저장소와 관련된 문제가 있는 경우

HttpDataError

DownloadItem.FailedReason.HttpDataError

HTTP 레벨에서 오류가 발생한 경우

InsufficientSpace

DownloadItem.FailedReason.InsufficientSpace

저장 공간이 부족한 경우

NoAccessRights

DownloadItem.FailedReason.NoAccessRights

접근 권한이 없는 경우

TooManyRedirects

DownloadItem.FailedReason.TooManyRedirects

리다이렉션이 많이 일어난 경우

Unauthorized

DownloadItem.FailedReason.Unauthorized

권한이 없는 경우

UnhandledHttpCode

DownloadItem.FailedReason.UnhandledHttpCode

다운로드 매니저가 처리할 수 없는 HTTP 코드를 받은 경우

Unknown

DownloadItem.FailedReason.Unknown

다운로드가 알 수 없는 이유와 함께 완료된 경우

DownloadItem.Status

import com.newin.nplayer.sdk.DownloadItem.Status

enum class Status

아이템의 현재 다운로드 상태를 나타냅니다.

Completed

DownloadItem.Status.Completed

다운로드를 완료한 상태

Downloading

DownloadItem.Status.Downloading

다운로드 중인 상태

Failed

DownloadItem.Status.Failed

다운로드를 실패한 상태

Paused

DownloadItem.Status.Paused

다운로드를 일시 정지한 상태

Pending

DownloadItem.Status.Pending

다운로드를 할 수 있는 상태 혹은 다운로드를 기다리는 상태

MediaPlayerActivityConfiguration.ScreenOrientationLock

import com.newin.nplayer.sdk.MediaPlayerActivityConfiguration.ScreenOrientationLock

enum class ScreenOrientationLock

화면 방향 고정 상태를 나타내는 열거형입니다.

Portrait

MediaPlayerActivityConfiguration.ScreenOrientationLock.Portrait

세로 방향으로 고정

Landscape

MediaPlayerActivityConfiguration.ScreenOrientationLock.Landscape

가로 방향으로 고정

Off

MediaPlayerActivityConfiguration.ScreenOrientationLock.Off

고정하지 않음

MediaPlayerActivityConfiguration.SubtitleDisplayPosition

import com.newin.nplayer.sdk.MediaPlayerActivityConfiguration.SubtitleDisplayPosition

enum class SubtitleDisplayPosition

현재 미디어의 자막 출력 위치를 나타냅니다.

OnScreen

MediaPlayerActivityConfiguration.SubtitleDisplayPosition.OnScreen

화면 위에 자막을 출력하는 모드

OnVideo

MediaPlayerActivityConfiguration.SubtitleDisplayPosition.OnVideo

비디오 위에 자막을 출력하는 모드

PlaybackFinishReason

import com.newin.nplayer.sdk.PlaybackFinishReason

enum class PlaybackFinishReason

재생 종료의 원인을 나타내는 열거형입니다.

Ended

PlaybackFinishReason.Ended

미디어가 끝까지 재생되어 종료된 경우

Error

PlaybackFinishReason.Error

오류로 인해 재생이 종료된 경우

UserExited

PlaybackFinishReason.UserExited

다른 미디어로 이동하거나 미디어를 종료하는 등 사용자가 미디어 재생을 제어한 경우

미디어 플레이어 화면

• 설정

• 컨트롤러 화면 구성

  • 상단 인터페이스

  • 메뉴

  • 중앙 인터페이스

  • 하단 인터페이스

• 키보드, 패드를 사용한 미디어 제어

설정

앞에 보여준 사용 방법대로 구현하여 presentMediaPlayer를 호출하면, 안드로이드 SDK의 미디어 플레이어 뷰를 사용할 수 있습니다.

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.media3.common.MediaItem
import com.newin.nplayer.sdk.extensions.presentMediaPlayer
import com.newin.nplayer.sdk.extensions.startMediaPlayerService
import com.newin.nplayer.sdk.withDrmConfiguration

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        startMediaPlayerService("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx")  // App 아이디
    }

    fun openMedia(uri: String) {
        val mediaItem = MediaItem.fromUri(uri) // "https://example.com/media.mp4"
            .withDrmConfiguration(
                appId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",  // App 아이디
                userId = "사용자 아이디"
            )
        presentMediaPlayer(mediaItem)
    }
}

컨트롤러 화면 구성

1. 화면 상단에 타임바를 중심으로하여, 왼쪽에 종료 버튼과 오른쪽에 메뉴 버튼이 있습니다. 우측에 화면 속 화면 버튼이 있습니다.
2. 화면 중앙의 왼쪽에는 화면 회전 잠금, 구간 반복, 트랙 설정 버튼이 있습니다.
3. 화면 중앙의 오른쪽에는 재생 속도와 관련된 버튼들이 있습니다.
4. 화면 하단에는 화면 잠금 버튼과 미디어 네비게이션 버튼, 화면 크기 조절 버튼이 있습니다.

화면 구성에 대한 더 자세한 설명은 아래를 참고하십시오.

• 상단 인터페이스

• 메뉴

• 중앙 인터페이스

• 하단 인터페이스

상단 인터페이스

1. 종료 버튼

미디어 플레이어를 종료합니다.

2. 타임바

사용자가 현재 재생 위치를 확인 하거나, 드래그나 클릭 등을 통해서 재생 위치를 변경할 수 있습니다.

왼쪽에는 현재 재생되는 위치가 시:분:초로 표시되며, 오른쪽에는 남은 시간이 표시됩니다.

위의 예제 그림을 보면, 미디어는 지금 10분 1초 부분을 재생하고 있고, 앞으로 4분 47초 남아있음을 나타냅니다.

재생 속도가 1이 아닐 경우에는 재생 속도를 고려하여 계산된 현재 재생 위치와 남은 시간을 아래 부분에 추가적으로 표시합니다.

아래의 그림은 재생 속도가 1.8배속일 때의 타임바를 보여줍니다.

3. 메뉴 버튼

메뉴를 엽니다.

4. 화면 속 화면 버튼

화면 속 화면 모드로 전환합니다. 안드로이드 8.0(API 수준 26)부터 사용 가능합니다. 보다 자세한 설명은 메뉴 내의 화면 속 화면을 참고하세요.

메뉴

재생 목록

현재 플레이어에 있는 재생 목록을 보여줍니다.

재생 목록에 있는 미디어 아이템을 선택하면, 재생 목록 화면은 닫지 않고, 해당 미디어 아이템을 재생합니다. 현재 재생되고 있는 아이템은 오른쪽 아이콘(✓)을 통해 확인할 수 있습니다. 완료 버튼을 클릭하면 재생 목록을 닫을 수 있습니다.

북마크

저장된 북마크 리스트를 보여줍니다.

우측 상단의 완료 버튼을 클릭하면 북마크 창을 닫을 수 있습니다.

좌측 상단의 플러스(+) 버튼을 클릭하여 현재 재생되고 있는 위치를 저장할 수 있습니다. 해당 버튼을 클릭하면, 북마크 제목을 넣을 수 있는 팝업창이 뜹니다. 확인을 클릭하여 현재 재생되는 위치를 북마크로 저장할 수 있습니다. 제목을 넣지 않아도, Untitled라는 이름의 북마크가 생성됩니다.

북마크 이름을 변경하려면 해당 아이템 행의 오른쪽에 있는 연필 버튼을 클릭하면 됩니다.

북마크를 삭제 하려면 해당 아이템 행의 맨 오른쪽의 휴지통 버튼을 클릭하면 됩니다.

화면 속 화면

화면 속 화면 모드를 활성화 하는 기능입니다. 상단 인터페이스의 화면 속 화면 버튼과 같은 기능입니다. 화면 속 화면 모드로 진입하면 아래와 같이 미디어가 표시됩니다.

화면 속 화면에 싱글 클릭하면, 다음과 같은 컨트롤러 화면이 나타납니다. 해당 화면은 안드로이드 8.0이상에서 기본적으로 제공되는 화면입니다.

1. 설정 버튼 화면 속 화면 모드에 대한 설정을 수정합니다.

2. X 버튼 재생중인 미디어 플레이어를 종료합니다.

3. 화면 속 화면 모드 종료 버튼 화면 속 화면 모드를 종료합니다.

4. 이전 버튼 현재 위치가 미디어의 처음 부분과 매우 가까울 경우에는 이전 미디어를 재생하고, 그렇지 않거나 이전 미디어가 없을 경우에는 현재 재생되는 미디어의 맨 앞으로 이동합니다.

5. 재생 / 일시 정지 토글 버튼 미디어가 재생 중이면 일시 정지를 하고, 일시 정지 중이면 재생합니다.

6. 다음 버튼 다음 미디어로 이동합니다. 만약 현재 미디어가 목록의 마지막이면 비활성화 됩니다.

중앙 인터페이스

1.화면 회전 잠금 버튼

화면 회전에 대한 플레이어의 기본 설정은 디바이스의 오리엔테이션에 맞춰서 화면이 회전하면서 크기가 변경되는 것입니다. 화면 회전 잠금 버튼을 활성화 시키면 디바이스가 어느 방향으로 회전해도 활성화 시켰을 당시의 화면 상태를 계속 유지합니다.

2. 구간 반복 버튼

구간 반복 버튼을 한 번 클릭하면, 구간 반복 모드로 들어갑니다. 반대로, 구간 반복 모드일 때 이 버튼을 다시 클릭하면 구간 반복 모드가 해제됩니다.

구간 반복 모드로 들어가면 화면 하단에 시작 위치와 종료 위치를 보여주는 버튼이 나타납니다. 위 그림처럼 버튼에 보이는 구간 사이를 반복하여 재생을 합니다.

버튼이 흰색일 경우는 각각 미디어의 맨 처음과 끝을 의미합니다. 버튼을 클릭하면 현재 위치를 업데이트 하며 구간 범위가 변경되고, 해당 버튼이 활성화된 색으로 변경 됩니다.

방금 눌렀던(활성화 된) 버튼을 한 번 더 클릭하면, 현재 위치를 업데이트를 하는 것이 아니라 입력된 기존 위치를 초기화 하여, 맨 처음 또는 맨 끝으로 위치가 변경되고 버튼이 흰색으로 변경됩니다.

예를 들어, 사용자가 구간 반복 버튼을 눌러 구간 반복 모드로 진입 한 뒤, 1분 20초일 때, 시작 위치 버튼을 클릭하여 시작 위치를 1분 20초로 설정합니다. 그리고, 2분 10초로 이동하여, 종료 위치 버튼을 클릭하여, 종료 위치를 2분 10초로 설정합니다. 그러면, 미디어는 1:20~2:10 구간을 반복해서 계속 재생합니다. 다시 한 번 종료 위치 버튼을 클릭하면, 2분 10초가 사라지고, 해당 미디어의 전체 길이에 해당하는 위치가 버튼에 표시되고 버튼은 흰색으로 바뀝니다. 이제, 미디어 재생이 끝나면 1분 20초로 돌아가 다시 재생합니다.

3. 트랙 설정 버튼

1) 비디오 트랙 설정

현재 재생되는 비디오 트랙이 간단한 정보와 함께 화면에 표시됩니다.

비디오 트랙을 클릭하면, 비디오 트랙을 선택할 수 있는 화면이 나옵니다.

2) 오디오 트랙 설정

현재 재생되는 오디오 트랙이 간단한 정보와 함께 화면에 표시됩니다.

오디오 트랙을 클릭하면, 오디오 트랙을 선택할 수 있는 화면이 나옵니다.

3) 자막 트랙 설정

현재 재생되는 미디어에 자막이 포함되어 있는 경우, 자막 보기 스위치 버튼을 사용하여, 자막을 끄고 켤 수 있습니다.

자막 보기를 활성화 하면, 해당 미디어가 가지고 있는 모든 자막이 표시되며, 해당 자막을 클릭하여 자막 설정을 합니다.

4. 재생 속도 증가 버튼

재생 속도를 0.1배 만큼 증가 시킵니다. 버튼을 클릭하면 화면 중앙에 증가된 재생 속도를 보여줍니다. 최대 4.0배 까지 가능합니다.

5. 재생 속도 복구 버튼

현재 재생 속도를 보여줍니다. 버튼을 클릭하면 재생 속도를 정상속도로, 즉 1로 되돌립니다.

6. 재생 속도를 감소 버튼

재생 속도를 0.1배 만큼 감소 시킵니다. 버튼을 클릭하면 화면 중앙에 감소된 재생 속도를 보여줍니다. 최소 0.1배 까지 가능합니다.

하단 인터페이스

1. 화면 잠금 버튼

화면을 잠급니다. 화면을 길게 꾹 누르는 것과 동일합니다. 화면 잠금을 풀기 위해서는 화면 가운데 있는 자물쇠 해제 버튼을 클릭하면 됩니다.

2. 이전 버튼

6번의 다음 버튼과는 다르게, 목록에 이전 미디어가 없어도 활성화 됩니다. 현재 위치가 미디어의 처음 부분과 아주 가까울 경우에는 이전 미디어를 재생하고, 그렇지 않거나 이전 미디어가 없을 경우에는 현재 재생되는 미디어의 맨 앞으로 이동합니다.

3. 되감기 버튼

한 번 클릭할 경우, 재생 위치를 seekBackIncrement(기본값: 10초) 전으로 이동합니다. 연속해서 클릭할 경우에는 재생할 위치를 계속하여 seekBackIncrement 전으로 업데이트합니다. 길게 꾹 누를 경우 이동할 위치를 계속해서 1초 전으로 업데이트합니다. 연속해서 클릭하거나 길게 꾹 누를 경우에는, 바로 이동하지는 않고, 사용자가 동작 혹은 입력을 멈출 경우 해당 위치로 이동합니다.

4. 재생/일시 정지 토글 버튼

미디어를 재생하거나 일시 정지할 수 있습니다.

5. 빨리 감기 버튼

한 번 클릭할 경우, 재생 위치를 seekForwardIncrement(기본값: 10초) 후로 이동합니다. 연속해서 클릭할 경우에는 재생할 위치를 계속하여 seekForwardIncrement 후로 업데이트 합니다. 길게 꾹 누를 경우 이동할 위치를 계속해서 1초 후로 업데이트합니다. 연속해서 클릭하거나 길게 꾹 누를 경우에는, 바로 이동하지는 않고, 사용자가 동작 혹은 입력을 멈출 경우 해당 위치로 이동합니다.

6. 다음 버튼

목록에서 다음에 재생할 미디어가 있을 경우에만 활성화 됩니다. 이 버튼을 선택하면, 다음 미디어를 재생합니다.

7. 화면 크기 조절 버튼

총 다섯 종류의 화면을 제공합니다.

RESIZE_MODE_FIT (기본)

화면비(aspect ratio)를 유지하며, 화면에 가려지는 것이 없이 미디어를 보여줄 수 있는 최대 크기

RESIZE_MODE_FIXED_WIDTH

화면비를 유지하며, 화면 폭(width)에 딱 맞게 미디어 크기를 조절

RESIZE_MODE_FIXED_HEIGHT

화면비를 유지하며, 화면 높이(height)에 딱 맞게 미디어 크기를 조절

RESIZE_MODE_FILL

화면비를 무시하고, 화면에 빈 틈이 없이 가득 채울 수 있도록 미디어 크기를 조절

RESIZE_MODE_ZOOM

화면비를 유지하며, 화면에 빈 틈이 없이 가득 채울 수 있도록 미디어 크기를 조절

키보드, 패드를 사용한 미디어 제어

presentMediaPlayer()를 호출하여 미디어 플레이어를 생성하면, 키보드 또는 패드로 미디어를 제어할 수 있습니다.

FAQ

컴파일 SDK 버전 오류 케이스

아래와 같은 오류가 생길 경우에는,

Project structure 윈도우를 열고, Modules 탭을 선택합니다. 그리고, Compile Sdk Version을 알맞게 수정하여 줍니다.

속성 업데이트가 안 되는 케이스

아래와 같이 매번 getMediaPlayer()를 사용하여 미디어 플레이어를 불러와서 속성을 업데이트 하는 경우에, 몇몇 속성들이 업데이트 되지 않는 경우가 있습니다.

Button(
    onClick = { 
        getMediaPlayer {
            it.muted = !it.muted	// 토글이 되지 않음
        }
    }
) {
    Text("Toggle mute")
}

매번 getMediaPlayer()를 사용하는 것이 아니라, 아래처럼 사용하시면 됩니다. 물론, 비동기로 미디어 플레이어를 가지고 온다는 사실은 잊지마세요.

val mediaPlayer: MediaPlayer? = null 

getMediaPlayer {
    mediaPlayer = it
} 

Button(
    onClick = { 
        val mediaPlayer = mediaPlayer ?: return
        mediaPlayer.muted = !mediaPlayer.muted	// 토글이 잘 됨
    }
) {
    Text("Toggle mute")
}

SDK 변경 이력

PlaynPlay SDK for iOS 연동 가이드

iOS SDK 다운로드

iOS SDK 샘플 다운로드

SDK 변경 이력은 여기에서 확인 가능합니다.

설정 방법

• 시작하기

• 프로젝트 생성

• 프로젝트 설정

  • iOS SDK 추가

  • Capability 추가

  • Destination 선택

시작하기

이 문서는 iOS용 PlaynPlay SDK(이하 iOS SDK) 사용 방법을 안내합니다.

iOS SDK는 Minimum Deployment는 13.0입니다.

프로젝트 생성

빈 프로젝트 만들기

File > New > New Project 를 선택하여, 프로젝트를 생성합니다. (단축키: ⇧ ⌘ N)

템플릿 선택

사용하고자 하는 템플릿을 선택하고, Next 버튼을 선택하여 다음으로 진행합니다.

프로젝트 설정 및 생성

Product Name, Team, Organization Identifier, Build Identifier, Interface, Language, Storage를 설정하고, Next 버튼을 누르고 다음 화면으로 갑니다.

그리고 저장할 디렉토리를 정하고, Create 버튼을 눌러서 프로젝트를 생성합니다.

프로젝트 설정

iOS SDK 다운로드

iOS SDK 다운로드

iOS SDK 샘플 다운로드

iOS SDK 추가

왼쪽 탭에서 방금 만든 프로젝트를 클릭하면 오른쪽에 아래 그림과 같은 설정 창이 열립니다. PROJECT 아래의 아이템이 선택되어 있으면, 여기에서 iOS Deployment Target 등 원하는 설정을 해주시면 됩니다.

TARGETS 아래에 있는 아이템을 선택하시면, 아래 그림처럼 세부사항이 나타납니다. 프로젝트를 처음 만들어서 화면이 열렸을 경우에는 TARGETS 아래 아이템이 이미 선택되어 있을 수도 있습니다.

General 탭을 선택한 뒤, 아래로 쭉 내리면 Frameworks, Libraries, and Embedded Content 섹션이 있습니다. SDK를 추가하기 위해서 + 버튼을 누릅니다.

프레임워크와 라이브러리를 선택하는 팝업에서 Add Files를 선택합니다.

Open 버튼을 클릭하여 제공받은 NPlayerSDK를 추가합니다.

다음과 같이 추가가 된 것을 확인합니다.

이제 swift 파일에서 import NPlayerSDK를 입력하여 SDK를 사용할 수 있습니다.

Capability 추가

General의 오른쪽에 있는 Signing & Capabilities 탭을 클릭합니다. 그리고 + Capability 를 클릭합니다.

현재 추가되어 있지 않은 Capability 목록이 화면에 나타납니다.

커서 있는 곳에서 Background Modes를 직접 입력하여 검색을 하거나 아래 목록에서 Background Modes를 찾아서, 더블 클릭을 하시면 해당 모드가 추가 됩니다.

추가한 Background Modes에서 Audio, AirPlay, and Pictures in Picture를 활성화합니다.

Destination 선택

다시 프로젝트로 돌아간 후, Run destination을 선택합니다. My Mac을 선택하면, 실 디바이스 없이 테스트 및 디버깅을 할 수 있습니다.

사용 방법

번들 아이디 추가

콘솔에 로그인하고 설정 > 애플리케이션으로 이동합니다.

아래 Bundle ID (Package name) 섹션에서 추가 버튼을 클릭합니다.

번들 아이디를 추가합니다.

번들 아이디는 Xcode의 설정 창에서 TARGETS 아래의 아이템을 선택한 후, General 탭 내의 Identity 섹션의 Bundle Identifier 에서 확인할 수 있습니다.

혹은 Signing & Capabilities 탭 내의 Signing 섹션에서 확인 및 수정할 수 있습니다.

AppDelegate 설정

미디어 재생 서비스를 설정하는 부분을 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?)에 추가합니다. 여기서 오디오 세션을 구성하고, App 아이디를 사용하여 DRM 기본 설정을 합니다.

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions:
    [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    MediaPlaybackService.initialize(appId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx") // App 아이디

    return true
}

App 아이디는 콘솔에서 설정 > 애플리케이션 > App ID > 보기를 클릭하여 확인 가능합니다. 복사하여 붙여넣기를 하실 수 있습니다.

다운로드 매니저를 사용하기 위해서 func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void)에 백그라운드 처리를 위한 부분을 추가합니다.

func application(
    _ application: UIApplication,
    handleEventsForBackgroundURLSession identifier: String,
    completionHandler: @escaping () -> Void
) {
    DownloadManager.shared.setBackgroundCompletionHandler(
        sessionIdentifier: identifier,
        completionHandler: completionHandler
    )
}

뷰 컨트롤러 구성

하나의 미디어 열기

func openMedia() {
    // DRM 설정을 합니다.
    let drmConfiguration = DrmConfiguration
        .Builder(
            appId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
            userId: "사용자 아이디"
        )
        .userData(userData) // 사용자 데이터(Callback URL에 전달한 데이터)
        .build()

    // 미디어 파일을 구성하며, DRM 설정을 합니다.
    let mediaItem = MediaItem.from(url: URL(string: "https://example.com/media.mp4")!)
        .buildUpon()
        .drmConfiguration(drmConfiguration)
        .build()
	
    // 미디어를 엽니다. 
    present([mediaItem], 0)
}

재생 목록으로 열기

iOS SDK에서 제공하는 present(mediaItems:startIndex:configuration:) 메서드를 사용하면, 쉽게 재생 목록을 열 수 있습니다.

let mediaItems: [MediaItem] = [ mediaItem1, mediaItem2, mediaItem3, ...]

present(mediaItems: mediaItems, startIndex: 0)

제목을 설정하는 예제

let mediaMetadata = MediaMetadata
    .Builder()
    .title("제목")
    .artworkUrl(URL(string:"https://www.example.com/image.jpg")!)
    .build()

let mediaItem = MediaItem
    .Builder(url: URL(string: "https://example.com/media.mp4")!)
    .mediaMetadata(mediaMetadata)
    .build()

자막을 추가하는 예제

let subtitleConfigurations = [
    SubtitleConfiguration
        .Builder(url: URL(string: "https://example.com/subtitle.vtt")!)
        .language("언어")
        .label("라벨")
        .mode(.autoSelect)
        .build(),
    ...
]

let mediaItem = MediaItem
    .Builder(url: URL(string: "https://example.com/media.mp4")!)
    .subtitleConfigurations(subtitleConfigurations)
    .build()

Seek 기능 제한

미디어 아이템을 구성할 때, seekable(false)을 사용하여 Seek 기능을 제한할 수 있습니다.

let mediaItem = MediaItem.Builder(url: URL(string: "https://example.com/media.mp4")!)
    .seekable(false)
    .build()

클래스

• AudioTrack

• DownloadManager

• DrmConfiguration.Builder

• MediaItem.Builder

• MediaMetadata.Builder

• MediaPlayer

• MediaPlayer.EventTarget

• MediaPlayerBaseViewController

• MediaPlayerViewController

• MediaTrack

• PlaybackInfoRepository

• SubtitleConfiguration.Builder

• TextTrack

• UIViewController

• VideoTrack

AudioTrack

class AudioTrack : MediaTrack  

MediaTrack를 확장한 클래스로, 오디오 트랙에 사용되는 클래스입니다.

속성

channels

var channels: Int! { get }

오디오 채널 수를 나타내는 속성입니다.

sampleRate

var sampleRate: Double! { get }

오디오 샘플링 레이트를 나타내는 속성입니다.

DownloadManager

다운로드 매니저를 사용하기 전에 반드시 AppDelegate 설정을 해야합니다.

func application(
    _ application: UIApplication,
    handleEventsForBackgroundURLSession identifier: String,
    completionHandler: @escaping () -> Void
) {
    DownloadManager.shared.setBackgroundCompletionHandler(
        sessionIdentifier: identifier,
        completionHandler: completionHandler
    )
}

위와 같은 부분을 추가하여야, 앱이 백그라운드인 상태가 되어도 다운로드 관련 작업을 원활하게 진행할 수 있습니다.

class DownloadManager : NSObject, URLSessionDownloadDelegate

다운로드 매니저 클래스는 아래와 같은 속성과 메서드를 가지고 있습니다.

정적 속성

shared

static let shared: DownloadManager { get }

다운로드 매니저에 접근하기 위한 정적 속성입니다. 아래에 언급되는 속성 및 메서드를 호출할 때, DownloadManager.shared를 사용하여 접근할 수 있습니다.

속성

downloadsUrl

var downloadsUrl: URL { get }

다운로드된 아이템이 저장되는 디렉토리 중 최상위 디렉토리를 나타내는 속성입니다.

items

var items: [DownloadItem] { get }

현재 다운로드 목록에 있는 아이템들을 반환하는 속성입니다.

maxParallelDownloads

var maxParallelDownloads: Int { get set }

동시에 받을 수 있는 아이템의 최대 개수를 반환하거나 설정합니다.

메서드

add(mediaItem:allowsCellularAccess:)

@discardableResult func add(
    mediaItem: MediaItem,
    allowsCellularAccess: Bool = true
) -> DownloadItem.Id

다운로드를 할 미디어 아이템을 추가합니다. 현재 다운로드가 진행되고 있는 아이템의 수가 maxParallelDownloads 보다 적으면 바로 다운로드를 시작합니다. 셀룰러 데이터 사용을 허용하지 않으려면, allowsCellularAccess를 false로 설정하여 호출하십시오.

addListener(_)

func addListener(_ listener: DownloadManager.Listener)

다운로드 매니저 리스너를 추가하기 위한 메서드입니다. 리스너를 추가한 후, 해당 리스너가 더 이상 필요 없을 떄는 반드시 removeListener(_) 메서드를 사용해서 제거하세요.

itemsByStatus(_)

func itemsByStatus(_ status: DownloadItem.Status) -> [DownloadItem]

특정 다운로드 상태의 아이템 목록을 가져오기 위해서 사용하는 메서드입니다.

pause(id:)

func pause(id: DownloadItem.Id)

다운로드를 일시 정지할 때 사용하는 메서드입니다.

pauseAll()

func pauseAll()

다운로드 목록에 있는 모든 아이템의 다운로드를 일시 정지하게 하는 메서드입니다.

remove(id:)

func remove(id: DownloadItem.Id)

다운로드 목록에서 아이템을 지울 때 사용하는 메서드입니다.

removeAll()

func removeAll()

다운로드 아이템 목록을 모두 지우는 메서드입니다.

removeCompleted()

func removeCompleted()

다운로드가 완료된 아이템을 목록에서 모두 지우는 메서드입니다.

removeListener(_)

func removeListener(_ listener: DownloadManager.Listener)

다운로드 매니저 리스너를 제거하기 위한 메서드입니다.

resume(id:)

func resume(id: DownloadItem.Id)

다운로드를 일시 정지한 아이템의 다운로드를 재개하는 메서드입니다.

resumeAll()

func resumeAll()

일시 정지한 모든 아이템의 다운로드를 재개하는 메서드입니다.

DrmConfiguration.Builder

class Builder

DRM 구성을 위해 초기 설정을 합니다. 제공받은 App 아이디와 사용자 아이디(User ID)를 입력하면 됩니다. .build()를 호출하여 구성을 완료합니다.

생성자

init(appId: String, userId: String)

메서드

build()

func build() -> DrmConfiguration

추가로 입력 받은 정보로부터 DRM을 최종 구성합니다.

offlineAccessPeriod(_)

func offlineAccessPeriod(_ offlineAccessPeriod: Duration?) -> DrmConfiguration.Builder

오프라인 재생 기한을 설정합니다.

userData(_)

func userData(_ userData: [String : Any]) -> DrmConfiguration.Builder

사용자 데이터(Callback URL에 전달할 데이터)를 추가합니다.

MediaItem.Builder

class Builder

미디어 아이템에 정보를 추가하고 싶을 때는 MediaItem.Builder()를 사용하면 됩니다. 정보 추가 후에는 .build()를 호출하여야 미디어 아이템으로 사용할 수 있습니다.

생성자

init(url: URL)

미디어 주소를 통해 미디어 아이템을 만들 수 있습니다.

메서드

build()

func build() -> MediaItem

Builder를 이용하여 설정한 정보에 기반하여 미디어 아이템을 만듭니다.

clippingConfiguration(_)

func clippingConfiguration(_ clippingConfiguration: ClippingConfiguration?) -> MediaItem.Builder

클리핑 설정을 넘겨줍니다.

disablePlaybackRate(_)

func disablePlaybackRate(_ disablePlaybackRate: Bool) -> MediaItem.Builder

배속 기능 허용 여부를 설정합니다. disablePlaybackRate(true)일 경우, 배속 기능이 제한됩니다.

drmConfiguration(_)

func drmConfiguration(_ drmConfiguration: DrmConfiguration?) -> MediaItem.Builder

DRM 설정을 넘겨줍니다.

mediaMetadata(_)

func mediaMetadata(_ mediaMetadata: MediaMetadata?) -> MediaItem.Builder

메타데이터 설정을 넘겨줍니다.

returnUrl(_)

func returnUrl(_ returnUrl: URL?) -> MediaItem.Builder

리턴 Url을 설정합니다.

seekable(_)

func seekable(_ seekable: Bool) -> MediaItem.Builder

Seek 기능 허용 여부를 설정합니다. seekable(false)일 경우, Seek 기능이 제한됩니다.

subtitleConfigurations(_)

func subtitleConfigurations(_ subtitleConfigurations: [SubtitleConfiguration]) -> MediaItem.Builder

자막 설정을 넘겨줍니다.

url(_)

func url(_ url: URL) -> MediaItem.Builder

미디어 주소를 변경합니다.

useBookmarkCallback(_)

func useBookmarkCallback(_ useBookmarkCallback: Bool)

MediaMetadata.Builder

class Builder

제목, 아트워크, 다운로드 경로를 추가할 때 사용합니다. .build()를 호출하여 구성을 완료합니다.

생성자

init()

파라미터 없이 미디어 메타데이터를 초기화합니다.

메서드

artworkUrl(_)

func artworkUrl(_ artworkUrl: URL?) -> MediaMetadata.Builder

아트워크를 추가합니다.

build()

func build() -> MediaMetadata

추가로 입력 받은 정보로부터 메타데이터를 최종 구성합니다.

title(_)

func title(_ title: String?) -> MediaMetadata.Builder

제목을 추가합니다.

MediaPlayer

class MediaPlayer

미디어 플레이어 클래스입니다. 활성화된 미디어 플레이어에 접근하는 방법은 player를 참고하세요.

속성

allowsBackgroundPlayback

var allowsBackgroundPlayback: Bool { get set }

백그라운드 재생을 허용할 지 여부를 나타내는 속성입니다.

allowsCellularAccess

var allowsCellularAccess: Bool { get set }

동영상을 재생(스트리밍)할 때, 셀룰러 데이터를 사용할 지 여부를 나타내는 속성입니다.

allowsPictureInPicturePlayback

var allowsPictureInPicturePlayback: Bool { get set }

화면 속 화면 모드를 허용할 지 여부를 나타내는 속성입니다.

audioTracks

var audioTracks: [AudioTrack] { get }

오디오 트랙 리스트를 반환하는 속성입니다.

autoplay

var autoplay: Bool { get set }

미디어가 로드되었을 때, 즉시 재생이 시작되어야 하는지를 나타내는 속성입니다. true면 자동 재생합니다.

buffered

var buffered: [TimeRange] { get }

버퍼에 있는 미디어 리소스의 범위를 반환합니다.

canStartPictureInPictureAutomatically

var canStartPictureInPictureAutomatically: Bool { get set }

앱이 백그라운드에 있을 때, 화면 속 화면 모드를 자동으로 시작할 수 있는지 여부를 의미하는 속성입니다.

currentMediaItem

var currentMediaItem: MediaItem? { get }

현재 재생 중인 미디어 아이템을 반환하는 속성입니다.

currentMediaItemIndex

var currentMediaItemIndex: Int { get }

현재 재생 중인 미디어 아이템의 index를 반환하는 속성입니다.

currentSrc

var currentSrc: URL? { get }

미디어 리소스의 uri를 반환하는 속성입니다.

currentTime

var currentTime: Duration { get set }

현재 재생 위치를 Duration 단위로 나타내는 속성입니다.

defaultMuted

var defaultMuted: Bool { get set }

오디오의 음소거 기본 설정을 나타내는 속성입니다.

defaultPlaybackRate

var defaultPlaybackRate: Float { get set }

미디어의 기본 재생 속도를 나타내는 속성입니다.

duration

var duration: Duration { get }

현재 미디어 길이를 반환하는 속성입니다. 재생 가능한 미디어가 없을 경우 0에 해당하는 Duration을 반환합니다.

ended

var ended: Bool { get }

미디어 재생 완료 여부를 반환하는 속성입니다.

error

var error: Error? { get }

최근 발생한 에러를 반환하는 속성입니다.

isFlippedHorizontally

var isFlippedHorizontally: Bool { get } 

현재 재생 중인 미디어 화면이 좌우 반전 상태인지 여부를 반환하는 속성입니다

isFlippedVerticaly

var isFlippedVerticaly: Bool { get }

현재 재생 중인 미디어 화면이 상하 반전 상태인지 여부를 반환하는 속성입니다.

isPictureInPictureActive

var isPictureInPictureActive: Bool { get }

현재 재생되는 미디어가 화면 속 화면 모드인지를 반환하는 속성입니다.

isPictureInPicturePossible

var isPictureInPicturePossible: Bool { get }

미디어가 화면 속 모드로 전환할 수 있는지 여부를 반환하는 속성입니다.

isSeekable

var isSeekable: Bool { get }

미디어에서 seek을 사용할 수 있는지 여부를 반환하는 속성입니다. 미디어의 길이가 파악이 될 경우 true를 반환합니다.

isSubtitlesVisible

var isSubtitlesVisible: Bool { get set }

화면에 자막 표시 여부. true나 false값을 넣어서 자막을 켜고 끌 수 있습니다.

loop

var loop: Bool { get set }

미디어 재생이 끝났을 때 다시 처음부터 재생할 지 여부를 나타내는 속성입니다.

maxSeekToPreviousPosition

var maxSeekToPreviousPosition: Duration { get set }

이전 버튼을 눌렀을 때, 이전 미디어로 갈 수 있는 최대 허용 위치를 나타내는 속성입니다. 메서드 seekToPrevious()에서 사용됩니다.

mediaItems

var mediaItems: [MediaItem] { get set }

미디어 아이템들의 목록을 나타내는 속성입니다.

muted

var muted: Bool { get set }

음소거 여부를 나타내는 속성입니다. 음소거면 true, 아니면 false입니다.

paused

var paused: Bool { get }

미디어가 일시 정지 상태인지 반환하는 속성입니다.

playbackRate

var playbackRate: Float { get set }

미디어의 재생 속도를 나타내는 속성입니다. 정상 속도는 1.0이고, 1보다 작을 때는 느리게, 1보다 클 때는 빠르게 재생합니다. 이 때, 오디오 피치 유지 여부는 preservesPitch의 값으로 제어할 수 있습니다.

playbackState

var playbackState: MediaPlayer.PlaybackState { get }