H5 플랫폼에서의 스트리밍 재생 제약과 기술적 대안

UniApp 프레임워크의 내장 video 컴포넌트는 네이티브 앱 환경에서는 높은 안정성을 제공하지만, H5 빌드 시 HLS(.m3u8) 또는 FLV(.flv) 포맷의 실시간 미디어 스트림을 처리할 때 기능적 한계가 명확합니다. 특히 다중 해상도 자동 전환, 커스텀 컨트롤 UI 적용, 그리고 모바일 브라우저에서의 인라인 재생(webkit-playsinline) 유지가 어려운 편입니다. 이러한 아키텍처적 공백을 메우기 위해 MUI-Player를 도입하는 것이 효율적인 접근법입니다.

해당 라이브러리는 hls.js 및 flv.js를 내부 디코더 레이어로 활용하여 표준 스트리밍 프로토콜을 브라우저 환경에서 안정적으로 해석합니다. 플러그인 기반의 확장 구조를 제공하므로 제어 바, 설정 패널, 해상도 선택기 등을 개발자가 원하는 형태로 재구성할 수 있습니다. 또한, 모바일 브라우저의 기본 풀스크린 동작을 우회하여 DOM 트리 내에서 비디오를 렌더링하는 인라인 모드를 지원하므로, UniApp의 하이브리드 렌더링 파이프라인과 높은 호환성을 가집니다.

패키지 의존성 구성 및 빌드 설정

프로젝트 루트 디렉토리에서 터미널을 실행하여 필수 모듈을 일괄 설치합니다. 단일 명령어를 통해 의존성 트리를 명확히 관리하면 번들 사이즈 최적화 및 버전 충돌 방지에 유리합니다.

npm install mui-player hls.js flv.js mui-player-desktop-plugin --save

• mui-player: 플레이어 코어 엔진 및 DOM UI 프레임워크
• hls.js: HTTP Live Streaming 프로토콜 클라이언트 라이브러리
• flv.js: Media Source Extensions(MSE) 기반 FLV 스트림 디코더
• mui-player-desktop-plugin: 데스크톱 환경 최적화 및 화질 전환 모듈

컴포넌트 기반 아키텍처 설계

유지보수성과 상태 관리의 명확성을 확보하기 위해 플레이어 로직을 독립적인 Vue 단일 파일 컴포넌트(SFC)로 캡슐화합니다. 다음 구현은 리소스 임포트, 라이프사이클 훅 연동, 그리고 동적 DOM 주입 컨테이너 정의를 포함합니다.

스크립트 구조 및 모듈 별칭 매핑

<script setup>
import { ref, onBeforeUnmount, defineProps, defineEmits } from 'vue'
import 'mui-player/dist/mui-player.min.css'

// 외부 라이브러리 별칭 재정의
import VideoCore from 'mui-player'
import HlsEngine from 'hls.js'
import FlvEngine from 'flv.js'
import DesktopExt from 'mui-player-desktop-plugin'

const props = defineProps({
  mediaUrl: String,
  showControls: Boolean,
  initialQuality: String
})

const emit = defineEmits(['stream-close', 'ready'])
const playerRoot = ref('stream-wrapper-' + Date.now())
let instance = null

const initializePlayer = () => {
  // props 및 디코더 설정을 기반으로 MUI-Player 인스턴스 생성
  // 실제 구현 시 hls.js / flv.js 디코더 매핑 로직 포함
}

onBeforeUnmount(() => {
  if (instance) {
    instance.destroy()
    instance = null
  }
})
</script>

템플릿 구조 및 오버레이 처리

<template>
  <section :id="playerRoot" class="media-container">
    <button 
      v-if="showControls" 
      class="overlay-dismiss" 
      @click.stop="emit('stream-close')">
      &#x2716;
    </button>
    <!-- MUI-Player 초기화 시 video 태그 및 컨트롤 UI가 해당 컨테이너 내부로 동적 주입됨 -->
  </section>
</template>