플레이어 조작

버튼·키보드·제스처로
학습자가 직접 다루는 재생 화면

Android SDK와 iOS SDK의 기본 플레이어 화면은 위·가운데·아래 세 줄과 메뉴로 짜여 있습니다. 학습자가 누르는 버튼과 운영자가 미리 정해 두는 값을 나눠서, 도입 회의에서 결정할 항목을 정리했습니다.

최종 수정 2026-10-28

Screen Layout

화면은 네 구역과 메뉴로 나뉩니다

앱이 presentMediaPlayer()(Android)나 present()(iOS)를 부르면 이 화면이 열립니다. 구역마다 학습자가 하는 일이 다릅니다.

구역	버튼	학습자가 하는 일
상단	종료, 타임바, 메뉴, 화면 속 화면	왼쪽에 현재 위치(시:분:초), 오른쪽에 남은 시간이 보입니다. 타임바를 끌거나 눌러 위치를 옮깁니다. 1배속이 아닐 때는 속도를 반영해 다시 계산한 위치와 남은 시간이 타임바 아래에 추가로 표시됩니다.
가운데 왼쪽	화면 회전 잠금, 구간 반복, 트랙 설정	기기를 돌려도 지금 방향을 유지하고, 반복할 구간을 잡고, 비디오·오디오 트랙과 자막을 고릅니다.
가운데 오른쪽	속도 올림, 1배 복귀, 속도 내림	한 번 누를 때마다 0.1배씩 바뀌고 바뀐 값이 화면 중앙에 뜹니다. 가운데 버튼은 현재 속도를 보여 주다가 누르면 1배로 돌아갑니다.
하단	화면 잠금, 이전, 되감기, 재생·일시 정지, 빨리 감기, 다음, 화면 크기	되감기·빨리 감기를 연달아 누르면 이동 폭이 쌓이고, 길게 누르면 1초씩 늘어납니다. 입력을 멈춘 순간 그 위치로 이동합니다.
메뉴	재생 목록, 북마크, 화면 속 화면	다른 차시로 옮기고, 지금 위치를 제목과 함께 저장합니다. 제목 없이 저장하면 이름이 Untitled가 됩니다.

두 플랫폼의 차이: 재생 목록에서 영상을 고르면 Android는 목록 창을 연 채로 재생하고 iOS는 목록 창을 닫습니다. 북마크 이름 변경과 삭제는 Android가 행 오른쪽의 연필·휴지통 버튼, iOS가 왼쪽 스와이프입니다. 북마크 저장 방식은 북마크 기능에서 다룹니다.

Speed & Repeat

배속과 반복은 학습자가 고르고, 시작값은 운영자가 정합니다

배속 범위는 0.1배부터 4.0배까지입니다. 반복은 학습자가 버튼으로 거는 방식과 앱이 코드로 거는 방식이 따로 있습니다.

Speed
시작 배속과 음정

플레이어가 열릴 때의 속도는 설정의 defaultPlaybackRate(기본 1.0)로 정합니다. 배속 중 음정 유지(preservesPitch)는 기본으로 켜져 있습니다. 배속을 아예 쓰지 못하게 할 영상은 미디어 단위로 따로 지정합니다.
영상별 시청 규칙 보기
A-B Repeat
버튼으로 거는 구간 반복

구간 반복 버튼을 누르면 화면 아래에 시작·끝 버튼이 생깁니다. 처음에는 영상의 맨 앞과 맨 끝을 가리키고, 누르는 순간의 위치로 바뀝니다. 바꾼 버튼을 한 번 더 누르면 맨 앞이나 맨 끝으로 되돌아갑니다. 1:20에 시작, 2:10에 끝을 누르면 그 50초가 계속 반복됩니다.
Repeat by App
앱이 거는 반복

앱은 repeatRange에 시작과 끝을 넣어 구간을 미리 걸 수 있고, 구간이 바뀔 때마다 RepeatRangeChange 이벤트를 받습니다. iOS는 반복 모드 none·one·all이 있어 all이면 목록의 마지막 영상 뒤에 첫 영상으로 돌아갑니다. Android는 loop 속성으로 끝난 영상을 처음부터 다시 재생합니다.

Keyboard · Pad · Gesture

입력별 동작과 운영자가 바꿀 수 있는 값

키보드나 패드를 연결한 기기에서도 같은 화면을 씁니다. 왼쪽·오른쪽 키는 Android 문서에서 방향 패드 키, iOS 문서에서 방향키로 부릅니다.

입력	동작	관련 설정
왼쪽·오른쪽 키	한 번 누르면 정해진 폭만큼, 누른 채 있으면 1초 단위로 계속 이동	이동 폭 `seekBackwardIncrement`, `seekForwardIncrement` (기본 10초). 화면의 되감기·빨리 감기 버튼도 같은 값을 씁니다
스페이스 키	재생과 일시 정지 전환	—
ESC 키	열린 대화 상자 닫기	—
한 번 탭	컨트롤러 표시·숨김	자동 숨김까지의 시간 `controllerShowTimeout` (기본 5초, 0으로 두면 계속 표시)
두 번 탭	화면 속 화면으로 전환	허용 여부 `allowsPictureInPicturePlayback` (기본 허용)
길게 누르기	화면 잠금. 가운데 자물쇠 버튼으로 해제	—
좌우 드래그	몇 초 앞뒤로 위치 이동	영상별 탐색 허용 여부 `seekable`
왼쪽 절반 위아래 드래그	화면 밝기 조정	—
오른쪽 절반 위아래 드래그	볼륨 조정	—

— 표시는 개발 문서에 따로 정하는 값이 없는 항목입니다. Android SDK는 2025년 12월 3일·5일과 2026년 1월 26일 버전에서 블루투스 키보드와 볼륨 키 입력 문제를 고쳤습니다. 키보드를 쓰는 학습자가 많다면 그 이후 SDK인지 확인하세요.

Fit · Zoom · Orientation

화면 맞춤 모드는 Android 5종, iOS 3종

하단 화면 크기 버튼이 모드를 차례로 바꿉니다. 성격이 같은 모드끼리 한 줄에 놓았습니다.

맞춤 방식	Android SDK	iOS SDK
비율 유지, 잘림 없이 최대 크기 (기본)	RESIZE_MODE_FIT	aspectFit
비율 유지, 빈틈 없이 채움	RESIZE_MODE_ZOOM	aspectFill
비율 무시, 화면 가득	RESIZE_MODE_FILL	fill
비율 유지, 폭에 맞춤	RESIZE_MODE_FIXED_WIDTH	—
비율 유지, 높이에 맞춤	RESIZE_MODE_FIXED_HEIGHT	—

iOS 문서는 화면 크기 모드를 세 가지로 적고 있습니다. 확대·축소 범위는 두 SDK 모두 2026년 7월 9일 버전부터 50~800%이고, 앱은 zoomVideo()에 기준점을 넘겨 특정 부분을 키울 수 있습니다. iOS는 좌우·상하 반전도 제공합니다. 학습자의 회전 잠금 버튼과 별도로, 운영자는 screenOrientationLock을 Portrait·Landscape·Off 중 하나로 정해 화면 방향을 처음부터 고정합니다.

Who Decides

운영자가 정하는 값, 학습자가 바꾸는 것

운영자 값은 Android MediaPlayerActivityConfiguration, iOS MediaPlayerViewController.Configuration에 담아 플레이어를 열 때 넘깁니다. 과정마다 값이 다르다면 과정별 설정 묶음을 미리 만들어 두면 관리가 편합니다.

항목	운영자 설정 (기본값)	학습자 화면 조작
배속	시작 속도 1.0, 0.1~4.0 범위에서 지정	속도 버튼으로 0.1배씩 조정
앞뒤 이동	각 10초	되감기·빨리 감기 버튼, 좌우 키
컨트롤러	5초 뒤 자동 숨김	한 번 탭으로 다시 표시
화면 방향	고정 안 함(Off)	회전 잠금 버튼
화면 속 화면	허용	상단 버튼, 메뉴, 두 번 탭
백그라운드 재생	꺼짐	—
셀룰러 데이터	허용	—
자막	영상 위, 맨 아래(1.0), 32픽셀, 배경 없음	자막 켜기·끄기, 여러 자막 중 선택
탐색·배속 허용	영상마다 `seekable`, `disablePlaybackRate`	영상별 규칙을 따름

화면 속 화면과 백그라운드 재생의 플랫폼별 차이는 화면 속 화면·백그라운드 재생, 자막 모양 설정은 자막 기능에서 이어집니다.

Custom UI

기본 화면을 바꾸고 싶을 때

버튼 배치까지 자사 디자인으로 바꾸려면 기본 화면 대신 상속용 클래스를 씁니다. 구성 방식은 세 단계로 나뉩니다.

Default
기본 화면 그대로

호출 한 번으로 이 페이지의 버튼이 모두 들어간 화면이 열립니다. 설정 묶음으로 기본값만 바꿉니다. 시범 운영이나 일정이 짧은 프로젝트에 권합니다.
Embed
앱 화면 안에 넣기 (Android)

MediaPlayerBaseFragment로 앱 화면 일부에 플레이어를 둡니다. 차시가 끝날 때마다 멈추게 하는 pauseAtEndOfMediaItems도 이 설정에 들어 있습니다.
Custom
컨트롤을 직접 디자인

Android는 영상·컨트롤·정보 영역 컨테이너를 가진 MediaPlayerBaseView를, iOS는 MediaPlayerBaseViewController를 상속합니다. iOS 문서는 구현 예를 샘플에서 보라고 안내합니다.
앱 연동 가이드

Decision Points

도입 회의에서 정할 다섯 가지

기본값으로도 재생은 됩니다. 다만 아래 다섯 가지는 과정 담당자와 앱 개발팀이 출시 전에 합의해 두기를 권합니다.

시작 배속과 배속 허용

인정 시간이 걸린 과정은 배속을 막을지, 복습용 과정은 1.2배처럼 빠르게 시작할지 정합니다.
앞뒤 이동 폭

5분 안팎의 짧은 강의와 두 시간짜리 세미나는 알맞은 폭이 다릅니다. 과정 길이별로 값을 나눠 둡니다.
화면 방향

세로로 찍은 강의가 있다면 Portrait 고정을, 판서 강의라면 Landscape 고정을 검토합니다.
컨트롤러 표시 시간

컨트롤러가 슬라이드 아래쪽 글씨를 가린다는 의견이 나오면 숨김 시간을 줄이고, 고령 학습자 과정이라면 늘립니다.
기본 화면 또는 직접 디자인

브랜드 화면이 꼭 필요한지, 출시 일정이 그 개발 기간을 감당하는지 따져 구성 방식을 고릅니다.