Stimulus를 이용한 뷰포트 외부 YouTube 비디오 자동 일시정지 구현

Auto-pause YouTube Videos with Stimulus | Rails Designer

작성자
Hotwire Weekly
발행일
2025년 07월 03일
원문 보기
railsdesigner.com

핵심 요약

  • 1 Stimulus와 Intersection Observer API를 활용하여 뷰포트 외부의 YouTube 비디오를 자동으로 일시정지하고, 다시 뷰포트 내로 들어오면 재생하는 기능을 구현합니다.
  • 2 YouTube iframe API의 복잡성(API 로딩, 플레이어 상태 관리 등)을 처리하며, `enablejsapi=1` 설정을 통해 JavaScript 제어 기능을 활성화합니다.
  • 3 이 컨트롤러는 HTML5 비디오 컨트롤러와 동일한 핵심 기능을 제공하면서 YouTube API의 특성을 효과적으로 통합합니다.

도입

이 글은 뷰포트 외부에 있는 임베디드 YouTube 비디오를 자동으로 일시정지하는 기능을 구현하는 방법을 탐구합니다. 이는 이전에 다루었던 네이티브 비디오 플레이어 컨트롤러와 마찬가지로 Stimulus와 Intersection Observer API를 활용합니다. 주요 과제는 YouTube의 iframe API와 통합하는 과정에서 발생하는 특정 복잡성을 처리하는 것입니다. 목표는 화면 밖의 비디오를 일시정지하고 다시 화면 안으로 들어올 때 재생하여 원활한 사용자 경험을 제공하는 것입니다.

1. Stimulus 컨트롤러 및 HTML 준비

  • data-controller="youtube"로 iframe을 감싸고, iframe src에 enablejsapi=1 추가.
  • data-youtube-target="player"로 iframe 지정. 컨트롤러는 player 타겟과 playing (재생 상태), percentageVisible (가시성 임계값) 값을 정의.

2. YouTube API 로딩 및 플레이어 초기화

  • connect() 시 #setup()으로 YouTube API 초기화. 중복 로드를 방지하며, 필요시 스크립트 로드 및 onYouTubeIframeAPIReady 콜백 설정.
  • #createPlayer()는 YT.Player 인스턴스 생성 및 이벤트 핸들러 등록.
    • onReady 시 IntersectionObserver 설정.
    • onStateChange 시 사용자의 수동 일시정지 처리.

3. 뷰포트 기반 비디오 재생 제어 로직

  • #detectViewport()는 IntersectionObserver를 생성하여 요소 가시성 모니터링 (percentageVisibleValue 기반 임계값).
  • #adjustPlayback(entry)는 가시성 변경 시 호출:
    • 뷰포트 밖에 있으면 #pauseWhenOutOfView()로 비디오 일시정지 및 playingValue를 true로 설정.
    • 뷰포트 안에 다시 들어오고 이전에 재생 중이었다면 (playingValue가 true), #attemptToPlay()로 비디오 재생 및 playingValue를 false로 재설정. YouTube playVideo()는 Promise를 반환하지 않음.

결론

이 Stimulus 컨트롤러는 뷰포트 외부의 YouTube 비디오를 효율적으로 일시정지하고, 뷰포트 내로 돌아오면 재생하는 기능을 제공합니다. YouTube iframe API의 특성을 성공적으로 통합하여, HTML5 비디오 컨트롤러와 동일한 핵심 사용자 경험을 유지하면서도 복잡한 API 상호작용을 깔끔하게 처리합니다. 이 구현은 Rails 애플리케이션에서 현대적이고 읽기 쉬운 JavaScript 코드를 작성하는 방법을 잘 보여주며, Intersection Observer API와 외부 비디오 API를 결합하는 실용적인 사례입니다.

관련 글들

뷰포트 이탈 시 비디오 자동 일시 정지 기능 구현

Stimulus와 Intersection Observer를 활용하여 뷰포트 이탈 시 비디오를 자동으로 일시 정지하고, 뷰포트 진입 시 재생을 재개하는 기능을 구현합니다.

06/19 읽어보기 →

Stimulus 컨트롤러를 활용한 스티키 요소 고정 상태 감지

CSS `position: sticky` 요소의 고정(stuck) 및 해제(unstuck) 상태 전환을 `IntersectionObserver` API와 Stimulus 컨트롤러로 정밀하게 감지하는 방법을 제시합니다.

01/03 읽어보기 →

Turbo Transition 소개

Turbo Transition은 DOM에 추가되거나 제거되는 요소에 부드러운 애니메이션 효과를 부여하는 커스텀 HTML 요소입니다.

06/12 읽어보기 →

Rails Turbo Drive 환경에서 서드파티 메신저 위젯 영속성 확보하기

Rails Turbo Drive의 <body> 교체 방식이 서드파티 iframe 기반 위젯의 상태 소실을 야기하는 문제를 분석합니다.

09/07 읽어보기 →

댓글 0

댓글 작성

0/1000
정중하고 건설적인 댓글을 작성해 주세요.

아직 댓글이 없습니다

첫 번째 댓글을 작성해보세요!