Mux & Astro

Mux는 모든 규모의 기업을 위한 비디오 스트리밍 인프라 및 성능 분석을 제공하는 미디어 호스팅 서비스입니다.

Mux를 사용하여 동영상 콘텐츠를 저장하고 호스팅하면, Mux Player용 Astro 네이티브 동영상 컴포넌트, Astro 프로젝트에 Mux 동영상을 추가하기 위한 드롭인 컴포넌트, 웹사이트에서 Mux로 동영상을 업로드하기 위한 Mux Uploader를 이용할 수 있습니다. 이러한 컴포넌트는 Mux Data와 원활하게 통합되어 동영상 참여도와 성과를 추적합니다.

Mux Node SDK를 통해 콘텐츠와 상호작용할 수도 있습니다.

Astro에서 Mux 사용하기

Mux의 API와 웹 컴포넌트는 Astro에서 작동하여 웹용 동영상과 스트림을 압축하고 최적화하며, 네트워크 상태에 따라 동영상 품질을 조정하고, 자막, 썸네일, 분석과 같은 추가 기능을 통합합니다. Mux Node SDK는 Mux Data와 Mux Video API를 모두 지원합니다.

전제 조건

기존 Astro 프로젝트. 일부 기능을 사용하기 위해 요청 시 렌더링을 위한 어댑터를 추가로 설치해야 할 수도 있습니다.
Mux 계정. 계정이 없는 경우, ASTRO 코드를 사용하여 Mux에 가입하면 50달러의 크레딧을 받을 수 있습니다.

Mux Player

Astro에서는, 최적화되고 반응성이 뛰어난 동영상 재생 및 라이브 스트리밍을 위한 모든 기능을 갖춘 Mux Player를 Astro의 네이티브 컴포넌트로 사용할 수 있습니다.

Mux Player는 비디오 플레이어 크기와 스트림 유형에 기반한 반응형 UI, 자동 썸네일 미리보기 및 포스터 이미지, 그리고 현대적인 비디오 플레이어 기능 (예: 전체 화면, PIP( 화면 속 화면), Chromecast, AirPlay)을 제공합니다.

---
import { MuxPlayer } from "@mux/mux-player-astro";
---
<MuxPlayer
  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
  metadata={{ video_title: 'Astro 동영상' }}
/>

Mux Player는 Mux Data의 분석 기능을 기본적으로 지원합니다. 배포된 사이트에서 동영상을 조회하면 대시보드에 방문자 참여도와 동영상 품질 지표가 표시됩니다.

설치하기

선호하는 패키지 관리자를 사용하여 Mux Player의 Astro 버전을 설치하세요.

npm install @mux/mux-player-astro

pnpm add @mux/mux-player-astro

yarn add @mux/mux-player-astro

Astro 프로젝트에서 Mux Player를 다음과 같이 사용할 수도 있습니다.

웹 컴포넌트 (@mux/mux-player의 <mux-player>)
React 컴포넌트 (@mux/mux-player-react의 <MuxPlayer />)
HTML 웹 임베드 (<iframe>)

Mux에서 동영상 재생하기

다른 Astro 컴포넌트와 마찬가지로, 네이티브 <MuxPlayer /> Astro 컴포넌트를 .astro 파일에 직접 가져와 사용하세요.

해당 자산의 playbackId가 필요합니다. 이는 Mux 대시보드에서 확인하거나 해당 자산의 ASSET_ID를 통해 조회할 수 있습니다.

Mux 웹 플레이어를 제어하는 다른 모든 옵션 (예: 컨트롤 표시/숨기기, 스타일 요소, 쿠키 비활성화)은 선택 사항입니다.

<MuxPlayer
  playbackId="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata={{
    video_title: 'Astro의 Starlight',
  }}
  style={{
    display: 'block',
    aspectRatio: '16/9',
    backgroundColor: '#000',
    margin: '1rem 0 2rem',
  }}
  primaryColor="#f2ec3a"
  secondaryColor="#0caa09"
  accentColor="#6e1e99"
  defaultShowRemainingTime={true}
/>

playbackId가 사전 녹화된 주문형 비디오가 아닌 라이브 스트림에 속하는 경우, DVR 모드 활성화 여부와 같은 옵션으로 Mux Player를 사용자 정의할 수 있습니다.

<MuxPlayer
  playbackId="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata={{
    video_title: 'Astro의 Starlight 스트림',
  }}
  streamType="live:dvr"
/>

모든 라이브 스트림은 향후 요청 시 재생할 수 있도록 Mux에 동영상 자산으로 녹화 및 저장됩니다.

Mux 비디오 요소

Mux 비디오 요소는 HTML5 <video> 요소를 대체하는 드롭인 대체 요소로, HLS 재생에 대한 브라우저 지원을 제공하며 방문자 및 성능 지표를 표시하도록 Mux Data가 자동으로 구성됩니다. Mux Player의 모든 기능이 필요하지 않거나 원하지 않을 때 사용하세요.

<mux-video> 웹 컴포넌트를 사용하려면 먼저 선호하는 패키지 관리자를 사용하여 mux-video를 설치하세요.

npm install @mux/mux-video

pnpm add @mux/mux-video

yarn add @mux/mux-video

그러면 .astro 파일의 <script> 태그에서 웹 컴포넌트를 가져와 렌더링할 수 있습니다.

동영상 자산의 playback-id가 필요합니다. 이는 Mux 대시보드에서 확인하거나 해당 자산의 ASSET_ID를 통해 조회할 수 있습니다.

HTML5 <video> 요소의 모든 속성 (예: poster, controls, muted)은 물론, Mux 비디오 플레이어 컨트롤 (예: 메타데이터 제공, 해상도 제어, 쿠키 비활성화)도 사용할 수 있습니다.

<script>import '@mux/mux-video'</script>

<mux-video
  playback-id="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata-video-title="Astro의 Starlight"
  controls
  disable-tracking
></mux-video>

Mux Node SDK

Mux Node SDK는 서버 측 TypeScript 또는 JavaScript에 Mux REST API에 대한 인증된 액세스를 제공합니다. 이를 통해 .astro 파일의 컴포넌트 스크립트에서 Mux 자산 및 데이터와 상호작용할 수 있습니다.

Mux Player 및 Mux Video 컴포넌트는 인증이 필요하지 않으며, playbackId만 있으면 공개적으로 접근 가능한 모든 동영상을 재생할 수 있습니다. 그러나 Node SDK를 통해 호스팅된 Mux 데이터에 연결하려면 Mux API 액세스 토큰이 필요합니다.

설치하기

선호하는 패키지 관리자를 사용하여 Mux Node SDK를 설치하세요.

npm install @mux/mux-node

pnpm add @mux/mux-node

yarn add @mux/mux-node

Mux 환경 API 액세스

API 토큰은 특정 Mux 환경에 연결됩니다. 이 환경은 기본적으로 동영상 및 관련 데이터를 담는 컨테이너 역할을 합니다. Mux에 가입하면 환경이 자동으로 생성됩니다. 추가 환경을 생성한 경우 토큰 생성 전에 올바른 환경을 선택해야 합니다. 이후 ID 및 SECRET 토큰을 획득하여 Node SDK에 제공할 수 있습니다. 이 토큰들은 .env 파일에 저장된 환경 변수로 Astro 컴포넌트에 전달될 수 있습니다.

이를 통해 동영상 정보 조회, 새 자산 생성, 메트릭 및 실시간 성능 확인 등을 위한 Mux Node SDK 인스턴스를 생성할 수 있습니다.

---
import Mux from "@mux/mux-node";

const mux = new Mux ({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET,
})
---

Astro 프로젝트에서 환경 변수를 사용하는 방법에 대해 자세히 알아보세요. 여기에는 Mux 자격 증명을 위한 타입 안전 스키마 생성도 포함됩니다.

자산 데이터 조회하기

Astro 프로젝트에서 사용할 동영상 정보를 가져오려면 동영상의 ASSET_ID (Mux 대시보드에서 확인 가능)를 retrieve() 도우미 함수에 제공하세요. 이를 통해 동영상 제목이나 재생 시간과 같은 값을 Mux 컴포넌트와 HTML 템플릿에 전달할 수 있습니다.

---
import Mux from "@mux/mux-node";
import { MuxPlayer } from "@mux/mux-player-astro";

const mux = new Mux({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET,
})

const ASSET_ID = "E01irAaN8c6dk1010153uC2mzst7RVbAdJJWtHECAHFvDo";
const asset = await mux.video.assets.retrieve(ASSET_ID);

const playbackId = asset.playback_ids?.find((id)=> id.policy=== "public")?.id;
const videoTitle = asset?.meta?.title;
const createdAt = Number(asset?.created_at);
const duration = Number(asset?.duration)

const date = new Date(createdAt * 1000).toDateString()
const time = new Date(Math.round(duration) * 1000).toISOString().substring(14, 19)
---
<h1>내 동영상 페이지</h1>
<p>제목: {videoTitle}</p>
<p>등록 날짜: {date}</p>
<p>길이: {time}</p>

<MuxPlayer
  playbackId={playbackId}
  metadata={{video_title: videoTitle}}
/>

Mux Asset API 문서에서 모든 자산 속성을 확인하세요.

Mux Uploader

Mux Uploader는 Astro 웹사이트를 위한 완전한 기능을 갖춘 사용자 정의 가능한 동영상 업로드 UI입니다. 네이티브 Astro <MuxUpload /> 컴포넌트를 사용하면 웹 애플리케이션에 동영상 업로드 기능을 구축할 수 있습니다.

Mux Uploader는 파일 업로드 시 수동 파일 선택과 드래그 앤 드롭 방식을 모두 지원하며, 업로드 일시 중지 및 재개 기능 등을 제공합니다.

설치하기

선호하는 패키지 관리자를 사용하여 Mux Uploader의 Astro 버전을 설치하세요.

npm install @mux/mux-uploader-astro

pnpm add @mux/mux-uploader-astro

yarn add @mux/mux-uploader-astro

Mux에 동영상 업로드하기

동영상을 업로드하기 전에 Mux API 액세스 토큰이 구성되어 있는지 확인하세요. 토큰이 구성되면 Mux Node SDK의 create() 함수를 사용하여 새 동영상 업로드를 시작할 수 있습니다.

---
import Layout from '../../layouts/Layout.astro';
import Mux from "@mux/mux-node";
import { MuxUploader } from "@mux/mux-uploader-astro";

const mux = new Mux({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET
});

const upload = await mux.video.uploads.create({
  new_asset_settings: {
    playback_policy: ['public'],
    video_quality: 'basic'
  },
  cors_origin: '*',
});
---
<Layout title="Mux에 동영상 업로드하기">
  <MuxUploader endpoint={upload.url} />
</Layout>

업로더 사용자 정의하기

추가 컴포넌트 속성을 사용하여 <MuxUploader />의 기능과 모양을 사용자 정의할 수 있습니다. 요소 스타일링 외에도, 다운로드 일시 중지 기능이나 최대 파일 크기 설정과 같은 옵션을 제어할 수 있습니다.

---
import { MuxUploader } from '@mux/mux-uploader-astro';
---

<MuxUploader
  endpoint="https://my-authenticated-url/storage?your-url-params"
  pausable
  maxFileSize={1000000000}
  chunkSize={8192}
  style={{
    '--progress-bar-fill-color': '#7e22ce',
    '--button-background-color': '#f0f0f0',
  }}
/>

추가 옵션은 Mux Uploader 사용자 정의 가이드를 참조하세요.

업로드 이벤트 처리하기

Mux Uploader는 풍부한 기능과 미디어 업로드의 현재 상태에 따라 변화하는 동적 UI를 제공합니다. 업로더의 동작은 사용자 주도 이벤트 (예: 파일 선택, 오류 후 재시도)와 상태 주도 이벤트(예: 업로드 진행 중, 업로드 성공 완료) 모두에 반응합니다.

이러한 이벤트를 수신 대기하고 Astro 컴포넌트의 클라이언트 측 스크립트에서 처리할 수 있습니다. MuxUploaderElement 타입도 사용할 수 있습니다.

---
import { MuxUploader } from '@mux/mux-uploader-astro';
---

<MuxUploader
  id="my-uploader"
  endpoint="https://my-authenticated-url/storage?your-url-params"
  pausable
/>

<script>
  import type { MuxUploaderElement } from '@mux/mux-uploader-astro';

  const uploader = document.getElementById('my-uploader') as MuxUploaderElement;

  uploader.addEventListener('uploadstart', (event) => {
    console.log('업로드가 시작되었습니다!', event.detail);
  });

  uploader.addEventListener('success', (event) => {
    console.log('업로드가 성공적으로 완료되었습니다!', event.detail);
  });

  uploader.addEventListener('uploaderror', (event) => {
    console.error('업로드 중 오류가 발생했습니다!', event.detail);
  });

  uploader.addEventListener('progress', (event) => {
    console.log('업로드가 진행 중입니다: ', event.detail);
  });
</script>

공식 리소스

전체 API 및 웹훅 참조, 사용 가이드, CMS 통합, 맞춤형 비디오 워크플로 구축 등 추가 주제에 대한 정보는 다음을 참조하세요.

더 많은 DAM 가이드

기여하기 커뮤니티 후원하기

Mux & Astro

Astro에서 Mux 사용하기

전제 조건

Mux Player

설치하기

Mux에서 동영상 재생하기

Mux 비디오 요소

Mux Node SDK

설치하기

Mux 환경 API 액세스

자산 데이터 조회하기

Mux Uploader

설치하기

Mux에 동영상 업로드하기

업로더 사용자 정의하기

업로드 이벤트 처리하기

공식 리소스

더 많은 DAM 가이드

Cloudinary

Mux