유튜브 영상을 배경으로 사용하게 해주는 플러그인

jQuery

작성일 2026-10-26 최근 수정일 2026-10-26

jquery.mb.YTPlayer는 YouTube 영상을 페이지 전체 또는 특정 요소의 배경으로 배치하는 jQuery 플러그인입니다. jQuery 전체 파일과 플러그인 CSS·JavaScript를 읽고, 높이가 있는 영역에 .YTPlayer()를 호출합니다. 영상이 재생되지 않아도 핵심 내용을 읽고 조작할 수 있도록 정적인 배경과 제어 버튼을 함께 준비해야 합니다.

필요한 파일과 실행 조건

개발자의 설치·옵션 문서에 따르면 이 플러그인은 HTTP 서버에서 실행해야 하며 file://로 연 파일과 jQuery slim은 지원하지 않습니다. 아래 예제는 전체 jQuery 3.7.1과 플러그인 3.4.6을 고정해 사용합니다. 플러그인의 패키지 정보에 선언된 jQuery 의존 범위도 3.x이므로, 사이트에서 jQuery 4를 사용한다는 이유로 이 예제의 버전을 바로 바꾸지 않습니다. 별도 페이지에서 플러그인과 함께 호환성을 확인해야 합니다.

로딩 순서는 jQuery → 플러그인 → 초기화 코드입니다. CSS도 반드시 포함합니다. 테마가 jQuery를 이미 제공하는 워드프레스에서는 본문에 두 번째 jQuery를 삽입하지 말고 테마나 플러그인의 스크립트 등록 기능에서 의존성을 관리합니다. 이 글의 HTML은 독립된 실습 파일입니다.

특정 영역에 배경을 넣는 전체 예제

다음을 UTF-8의 ytplayer-demo.html로 저장합니다. 영상은 YouTube 공식 API 문서에 사용되는 예제 ID를 사용했습니다. 실제 사이트에서는 소유·이용 권한과 임베드 허용 여부가 적절한 영상을 선택합니다. 배경 영역에는 장식 영상만 두고 제목·설명·버튼은 바깥에 두었습니다.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>YouTube background with a static alternative</title>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/jquery.mb.YTPlayer/3.4.6/css/jquery.mb.YTPlayer.min.css">
  <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.mb.YTPlayer/3.4.6/jquery.mb.YTPlayer.min.js"></script>
  <style>
    body { font: 16px/1.6 sans-serif; max-width: 900px; margin: 20px; }
    #video { width: 100% !important; height: 340px !important; padding: 0 !important; overflow: hidden; position: relative; background: linear-gradient(120deg,#164e63,#0f766e); }
    button { font: inherit; margin: 4px; }
    #status { overflow-wrap: anywhere; }
  </style>
</head>
<body>
  <h1>A background is optional</h1>
  <p>This text remains readable without video. Loading connects to YouTube.</p>
  <button type="button" id="load">Load YouTube background</button>
  <button type="button" id="play" disabled>Play</button>
  <button type="button" id="pause" disabled>Pause</button>
  <button type="button" id="static">Static background / reload</button>
  <p id="status" role="status">Static background; video not requested.</p>
  <div id="video" aria-hidden="true"></div>
  <p>Keep important content and controls outside this decorative region.</p>
  <script>
    document.querySelector("#static").addEventListener("click", function () { location.reload(); });
    document.querySelector("#load").addEventListener("click", function () {
      const status = document.querySelector("#status");
      if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
        status.textContent = "Reduced motion: keeping the static background."; return;
      }
      if (!window.jQuery || typeof jQuery.fn.YTPlayer !== "function") {
        status.textContent = "Dependency unavailable; keeping the static background."; return;
      }
      this.disabled = true;
      status.textContent = "Loading; playback is not yet confirmed.";
      const $video = jQuery("#video");
      const timer = setTimeout(function () {
        status.textContent = "Still waiting; use Static background / reload if needed.";
      }, 15000);
      $video.on("YTPPlay", function () {
        clearTimeout(timer); status.textContent = "Playing muted background.";
        jQuery("#pause").prop("disabled", false);
      }).on("YTPPause", function () {
        status.textContent = "Paused."; jQuery("#pause").prop("disabled", true);
      });
      $video.YTPlayer({
        videoURL: "M7lc1UVf-VE", containment: "self", ratio: "16/9",
        autoPlay: true, mute: true, loop: true, showControls: false,
        useOnMobile: false, useNoCookie: true, gaTrack: false,
        stopMovieOnBlur: true,
        onReady: function () {
          clearTimeout(timer); status.textContent = "Player ready; use Play if playback does not start.";
          jQuery("#play").prop("disabled", false);
        },
        onError: function (player, error) {
          clearTimeout(timer);
          status.textContent = "YouTube error " + error.data + "; use Static background / reload.";
        }
      });
      jQuery("#play").on("click", function () { $video.YTPPlay(); });
      jQuery("#pause").on("click", function () { $video.YTPPause(); });
    });
  </script>
</body>
</html>

처음에는 다음 상태이며 YouTube 영상 요청을 시작하지 않습니다. 다만 jQuery·플러그인 CDN 파일은 페이지를 열 때 읽습니다.

Static background; video not requested.

Python이 설치되어 있다면 PowerShell에서 해당 파일이 있는 폴더로 이동한 뒤 다음 명령을 실행합니다. 다른 웹 서버를 사용해도 되며, 포트 8000을 이미 사용 중이라면 사용 가능한 포트로 바꿉니다.

python -m http.server 8000 --bind 127.0.0.1

http://127.0.0.1:8000/ytplayer-demo.html을 엽니다. 파일을 더블 클릭해 file://로 열지 않습니다.
Load YouTube background를 누릅니다. 외부 YouTube 연결과 플레이어 준비가 시작됩니다.
실제 재생 이벤트가 오면 Playing muted background.가 표시되고 Pause가 활성화됩니다. 준비 상태만으로 재생 성공을 판단하지 않습니다.
준비는 됐지만 재생이 안 되면 Play를 누릅니다. Pause는 일시 정지하며, 재생 정책이나 외부 오류까지 해결해 주는 버튼은 아닙니다.
Static background / reload는 문서 전체를 다시 읽어 영상과 이전 요청을 끝내고 초기 상태로 돌아갑니다. 이 실습의 다른 화면 상태도 초기화됩니다.
서버를 끝내려면 명령 창에서 Ctrl+C를 누릅니다.

Windows Edge와 jQuery 3.7.1에서 실제 플러그인 초기화, 외부 요청 차단 시 대기 상태, 의존 파일 실패, 동작 줄이기와 다시 읽기를 검증했습니다. 외부 YouTube 영상의 스트리밍 성공 여부는 네트워크 결과에 따라 별도로 판단해야 하며, 이 검증을 모든 기기에서의 재생 보장으로 해석하지 않습니다.

옵션과 재생 상태 해석하기

containment: "self"는 선택한 요소 자체를 배경 영역으로 사용합니다. 높이가 0이면 영상이 보이지 않으므로 예제는 폭 100%·높이 340px·padding=0을 !important로 지정해 플러그인의 인라인 크기와 비율용 여백보다 우선했습니다. body를 지정하면 페이지 전체 배경이 되지만 본문의 겹침·배치까지 달라져, 먼저 제한된 영역에서 작동을 확인하는 편이 쉽습니다. 16:9 영상을 세로에 가까운 영역에 채우면 일부가 잘릴 수 있으므로 주요 정보가 담긴 영상을 배경으로 삼지 않습니다.

mute: true는 음소거, loop: true는 반복 요청, autoPlay: true는 준비 후 재생 시도입니다. 브라우저 자동 재생 정책과 iframe 권한, 기기 상태에 따라 결과가 달라질 수 있습니다. onReady는 API 준비이며 실제 재생은 YTPPlay로 구분했습니다. 15초 대기 문구는 오류 판정이 아니라 아직 확인되지 않았다는 안내입니다.

useOnMobile: false로 플러그인이 모바일로 판별한 환경에서는 배경 영상을 사용하지 않습니다. CSS 그라데이션은 그대로 남습니다. 좁은 데스크톱 창을 보는 것은 실제 휴대전화 검증을 대신하지 않습니다. 동작 줄이기 설정이 reduce면 Load를 눌러도 초기화를 건너뜁니다. 예제는 클릭 시 설정을 확인하므로 이미 재생 중일 때 운영체제 설정을 바꾸는 경우까지 자동으로 추적하지 않습니다.

useNoCookie: true는 플러그인이 youtube-nocookie.com을 사용하게 하는 옵션이며, 외부 연결이나 모든 데이터 처리가 사라진다는 뜻은 아닙니다. 예제의 첫 로드 버튼은 연결 시점을 분명히 하는 장치입니다. 실제 사이트의 개인정보 안내·설정은 사용하는 서비스와 운영 정책에 맞춰 별도로 정합니다.

재생 실패와 플랫폼 제약 확인하기

영역이 비면 개발자 도구 Network에서 jQuery·플러그인·CSS 응답과 YouTube 요청을 확인합니다. Console의 첫 오류를 먼저 해결하고, 방화벽·차단 확장·사이트의 Content Security Policy도 확인합니다. API가 오지 않는 경우에는 onError까지 실행되지 않을 수 있으므로 대기 문구와 정적 화면 복원 버튼이 필요합니다.

YouTube IFrame API 오류 문서에서 100은 삭제·비공개 등 찾을 수 없는 영상, 101·150은 임베드 금지, 153은 HTTP Referer 또는 동등한 클라이언트 식별 정보가 없는 요청을 뜻합니다. 임의의 no-referrer 설정을 해결책으로 추가하지 말고 서버·웹뷰·브라우저 요청의 실제 조건을 점검합니다.

플러그인의 showControls는 플러그인 제어 UI를 조절하는 옵션이며 광고·YouTube 표식을 전부 제거한다는 약속이 아닙니다. 현재 YouTube 플레이어 매개변수에서는 modestbranding 등의 폐기된 옵션도 확인할 수 있습니다. quality에 highres를 넣었다고 항상 최고 화질이 강제되는 것도 아니므로, 서비스가 결정하는 품질·표시를 전제로 설계합니다.

배경 영상은 장식이므로 메뉴·본문·구매 같은 핵심 동작이 영상 성공에 의존하지 않게 합니다. 영상 자체를 시청해야 내용을 이해한다면 장식 배경 대신 조작 가능한 일반 플레이어와 필요한 자막·설명을 제공하는 구성이 적합합니다.

jQuery