유튜브 IFrame API로 음악 플레이어 만들기

date

Jan 12, 2026

slug

youtube-iframe-music-player

author

status

Public

왜 음악 플레이어를 붙이려고 했을까

음악이 있는것과 없는 것의 표현하는 분위기는 다르다고 생각합니다. 음악을 넣은 프로젝트가 모바일 청첩장과 현재 개발중인 공개 다이어리입니다. 이전의 프로젝트들을 회고하면서 노래가 있으면 좋겠다는 생각을 해보았고 다음의 프로젝트들에서 진행해보았습니다. 모바일 청첩장은 음악 파일을 집어넣는 형태로 개발을 했어봤는데 해당 방식으로 자동재생으로 진행했던 부분은 후에 작성해보도록 하겠습니다. 다만 음악파일을 많이 집어넣으면 용량이나 여러가지로 문제가 될 수 있다고 생각해서 방법을 찾아보다가 유튜브 API를 촬용해보기로 하였습니다.

처음 고민했던 선택지들

1. iframe embed

가장 단순히 iframe으로 노출하는 방식입니다.


<iframe src="https://www.youtube.com/embed/..." />

❌ 문제점

재생 상태를 알 수 없음

다음 곡 구현 불가

UI 제어 거의 불가능

단순히 영상을 띄우는 용도라면 괜찮지만, 플레이어로 쓰기엔 한계가 분명했습니다.

2. react-player 라이브러리

라이브러리만 활용하면 되어서 구현이 빠르고 유튜브 링크를 바로 사용 가능했습니다.

❌ 문제점

내부 구현이 많이 추상화되어 있음

플레이리스트 제어가 애매함

커스텀 UX에 한계

그래서 각각의 서비스에 맞는 플레이어를 만들기엔 부족했습니다.

3. YouTube IFrame Player API

추가적으로 세팅과 구현을 해야했지만 원하는 UX를 만들 수 있는 유일한 선택지였기에 해당 방법으로 최종 선택하였습니다.

핵심 구현 구조

1. IFrame API는 전역 스크립트

YouTube IFrame API는 import 방식이 아닙니다. 스크립트를 로드하면 window.YT가 생성되는 구조이기에 반드시 지켜야 할 조건들이 있습니다.

한 번만 로드할 것

로드 완료 이후에만 Player 생성할 것


export function loadYouTubeIframeAPI():Promise<void> {
  if (window.YT?.Player) return Promise.resolve();

  return new Promise((resolve) => {
    const tag = document.createElement("script");
    tag.src ="https://www.youtube.com/iframe_api";
    window.onYouTubeIframeAPIReady = () => resolve();
    document.head.appendChild(tag);
  });
}

2. React Hook으로 플레이어 생명주기 관리

플레이어를 컴포넌트에 바로 두면 mount / unmount 시 관리가 어려워지기 때문에 custom hook으로 분리했습니다.


const playerRef = useRef<YTPlayer | null>(null);

useEffect(() => {
  loadYouTubeIframeAPI().then(() => {
    playerRef.current = new window.YT.Player(container, {
      videoId,
      events: {
        onStateChange: (e) => {
          if (e.data === 0) onEnded?.(); // ENDED
        },
      },
    });
  });

  return () => {
    playerRef.current?.destroy();
    playerRef.current = null;
  };
}, []);

페이지 이동 시 iframe이 남는 문제를 깔끔하게 해결할 수 있었습니다.

3. autoplay 불가능

가장 많이 만나는 문제로 페이지 로드 후 자동 재생이 안되고 사용자 클릭 이후 재생이 되도록 하는 정책입니다.


// 영상 교체 시
player.cueVideoById(videoId);

// 실제 재생은 버튼 클릭에서
player.playVideo();

이 방식이 데스크탑, 모바일 모두에서 가장 안정적이었습니다.

플레이리스트 구성 방식

유튜브의 공식 playlist는 쓰지 않고 배열 기반 플레이리스트가 더 단순했기에 제가 좋아하는 노래들로 채워넣었습니다.


const TRACKS = [
  { title: "곡 제목", artist: "가수", url: "youtube link" },
];

구조는 다음과 같습니다.

URL → videoId 추출

index로 현재 곡 관리

ENDED 이벤트 → 다음 곡

정리하며

이번 구현에서 가장 중요했던 건 기술보다 공식 API를 쓰되 과하지 않게, 서비스 분위기에 맞도록하는 UX였습니다. 유튜브 음악 플레이어는 있어도 되고 없어도 되는 기능일 수 있지만 잘 만들면 글을 읽는 경험 자체를 바꿀 수 있다고 생각합니다