설정 사전: 음악 플레이어
플레이어 활성화, 재생목록, 오디오 경로, UI 문구를 설정합니다.
목차
내 곡 한 개부터 넣으려면 음악 설정 가이드를 읽으세요. 설정 위치는 설치와 사이트 정보, 다른 모듈은 설정 사전 시작 페이지에 있습니다.
설정은 src/site.config.ts의 theme.music입니다. 테마 기본은 플레이어 꺼짐과 빈 목록이며 곡을 포함하지 않습니다. demo의 개인 재생목록이 아닌 패키지 기본값을 설명합니다.
theme.music.enabled: 플레이어 스위치
- 타입 / 기본값: boolean / false.
- 상태와 역할: 적용됩니다. true이며 유효 곡이 하나 이상일 때 공용 프레임워크에 렌더링합니다.
- 제한: 곡 없이 true만 쓰면 표시하지 않습니다. 끄면 유효 실행 목록에 곡을 넣지 않고 항목별 검증을 건너뜁니다. 설정·public 오디오는 지우지 않으며 공개 파일 직접 접근도 제한하지 않습니다.
- 예시:
theme: { music: { enabled: false } }.
사이트 공통 스위치이며 홈·언어별 스위치는 아닙니다. 공용 프레임워크 표준 페이지가 같은 목록을 공유하므로 홈에서만 재생하는 것이 아닙니다. 사용자 페이지의 연결 여부는 페이지 자체가 정합니다.
theme.music.tracks: 곡 목록
- 타입 / 기본값: MusicTrack[] / []. 항목의 세 필드는 아래와 같습니다.
- 상태와 역할: 음악을 켜면 조건부 적용합니다. 배열순으로 목록을 표시하고 곡을 전환하며 공개 개수 상한은 없습니다.
- 제한: 켜면 배열이어야 합니다. 빈 배열도 유효하지만 유효 플레이어 상태는 꺼짐이 됩니다. 배열 전체를 대체하며 기본·이전 목록과 합치지 않습니다. 새 곡을 추가할 때 유지할 항목도 남기세요.
- 예시 값: [{ title: ‘나의 노래’, artist: ‘작성자’, src: ‘
/music/my-song.mp3’ }].
제목·작성자·주소는 전역 배열에 있으며 i18n 문구가 아닙니다. 언어 전환이 목록을 바꾸지 않습니다. 외부 플랫폼의 목록 객체나 공유 링크를 이 배열로 쓰지 마세요.
곡별 필드
전체 접두사는 theme.music.tracks[]입니다. “없음”은 사용자 항목에 자동 보완이 없다는 뜻입니다.
| 필드 | 타입 / 기본값 | 상태·역할·제한 | 예시 값 |
|---|---|---|---|
| title | string, 필수 / 없음 | 조건부 적용: 주 표시·접힘 제목·목록의 곡 이름입니다. 비어 있지 않은 문자열이며 앞뒤 공백을 제거합니다. 빈 제목은 오류이고 파일 이름·오디오 태그에서 생성하지 않습니다. | ‘나의 노래’ |
| artist | string, 생략 가능 / 미설정, ’’로 정규화 | 조건부 적용: 주 영역·목록의 작성자입니다. 입력하면 string이며 공백을 제거합니다. 빈 값에 사이트 작성자를 넣거나 메타데이터를 읽지 않습니다. | ‘작성자’ |
| src | string, 필수 / 없음 | 조건부 적용: 단일 / 또는 소문자 https://로 시작하며 공백·역슬래시는 안 됩니다. HTTPS는 URL 해석도 통과해야 합니다. 존재·오디오 내용은 검사하지 않습니다. | ‘/music/my-song.mp3’ |
title·artist는 일반 텍스트이며 Markdown·HTML을 해석하지 않습니다. 표지, 가사, 길이, 앨범, 독립 ID, 곡별 음량 필드는 없습니다.
src 제한은 다음과 같습니다.
- 로컬은
public/music/를 권장하고 /music/파일명으로 씁니다. public 접두사, Windows 경로, src/assets 경로는 안 됩니다. 규칙에 맞는 다른 루트 경로도 받으며 /music/이나 확장자를 강제하지 않습니다. - http://, //example.com/file.mp3, data:, blob:, 일반 상대 경로는 안 됩니다. HTTPS 접두사는 대소문자를 구분하므로 소문자를 쓰세요.
- 주소에 직접 공백을 넣지 마세요. 필요하면 URL 인코딩하되 실제 파일 존재를 보장하지는 않습니다. 앞뒤 공백도 넣지 마세요.
- 렌더링 시 루트 경로에 Astro BASE_URL을 자동 추가합니다. 하위 배포에서 같은 접두사를 중복 추가하지 마세요. HTTPS는 유지합니다.
- 형식 통과는 접근·지원 보장이 아닙니다. 브라우저가 지원하고 접근할 수 있어야 하며 플랫폼 공유 페이지는 직접 오디오가 아닙니다. 외부는 fetch 다운로드하므로 CORS가 필요합니다. 새 탭 재생 성공만으로 CORS 허용을 판단하지 마세요.
src로 저장된 곡을 복원하므로 곡마다 다른 주소를 권장합니다. 중복 src를 금지하지 않지만 첫 일치 항목으로 복원하며 제목은 식별자가 아닙니다.
병합 가능한 재생목록 예시
먼저 public/music/my-song.mp3를 준비하세요. 경로는 예시이며 테마가 오디오를 만들지 않습니다. src/site.config.ts의 기존 defineThemeConfig({...})에 합치고 import, export, 개인 설정을 유지하며 theme를 중복 생성하지 마세요.
theme: {
music: {
enabled: true,
tracks: [
{
title: '나의 노래',
artist: '작성자',
src: '/music/my-song.mp3',
},
],
},
},
플레이어만 끄려면 목록을 비우지 말고 enabled: false로 설정하세요. 개발 서버는 수정 설정을 다시 읽어야 하며 온라인은 재빌드·재배포해야 합니다. 오디오만 올려도 tracks에 등록하지 않으면 목록에 자동 포함되지 않습니다.
messages.music: UI·접근성 문구 열아홉 개
전체 접두사는 i18n.locales.<locale>.messages.music.입니다. 모두 선택적 string이며 현재 언어 내장값·대체 연결을 사용합니다. 표에는 중국어 간체 / 영어 기본값과 한국어 예시를 제공합니다. 플레이어와 해당 컨트롤·상태가 나타나야 적용합니다. 빈 문자열은 문구만 덮어쓰며 기능 숨기기가 아니고 접근성 이름을 불명확하게 만들 수 있습니다.
| 필드 | 중국어 간체 / 영어 기본값 | 역할·제한 | 한국어 예시 값 |
|---|---|---|---|
label |
音乐播放器 / Music player | aside의 접근 가능한 이름이며 상단 AUDIO CHANNEL 문구는 아닙니다. | "음악 플레이어" |
play |
播放 / Play | 재생 버튼 이름이며 보이는 문구는 PLAY입니다. | "재생" |
pause |
暂停 / Pause | 재생·로드 중 버튼 이름이며 보이는 문구는 PAUSE입니다. | "일시 정지" |
prev |
上一首 / Previous | 이전 곡 버튼 이름이며 보이는 문구는 PREV입니다. | "이전 곡" |
next |
下一首 / Next | 다음 곡 버튼 이름이며 보이는 문구는 NEXT입니다. | "다음 곡" |
open |
展开播放器 / Open player | 접힌 상태에서 펼치기 버튼 이름이며 문구는 OPEN입니다. | "플레이어 펼치기" |
close |
收起播放器 / Collapse player | 펼친 상태에서 접기 버튼 이름이며 문구는 MIN입니다. 접어도 재생은 멈추지 않습니다. | "플레이어 접기" |
progress |
播放进度 / Progress | 진행 슬라이더 이름이며 진행·탐색 범위는 바꾸지 않습니다. | "재생 위치" |
volume |
音量 / Volume | 음량 슬라이더 이름이며 초기 음량은 설정하지 않습니다. 가시 라벨은 LVL입니다. | "음량" |
queue |
歌单 / Playlist | 재생목록 펼치기 이름이며 QUEUE·SHOW / HIDE는 고정입니다. | "재생 목록 펼치기 또는 접기" |
mute |
静音 / Mute | 음소거 전 버튼 이름이며 가시 문구는 MUTE입니다. | "음소거" |
unmute |
取消静音 / Unmute | 음량 0일 때 복원 버튼 이름이며 가시 문구는 UNMUTE입니다. | "음소거 해제" |
idle |
就绪 / Ready | 초기·곡 전환 뒤 SIGNAL 상태입니다. | "재생 대기" |
loading |
加载中 / Loading | 곡 다운로드·재생 대기 SIGNAL 상태입니다. | "곡을 불러오는 중" |
playing |
播放中 / Playing | 재생 중 SIGNAL 상태입니다. | "재생 중" |
paused |
已暂停 / Paused | 일시정지 SIGNAL 상태입니다. | "일시 정지됨" |
blocked |
浏览器阻止了自动播放,请点击 PLAY 继续播放。 / Click Play to continue. Your browser blocked automatic playback. | 브라우저 재생 거부 안내이며 문구로 제한을 해제할 수 없습니다. | "계속하려면 재생을 누르세요." |
error |
播放失败,请重试或切换歌曲。 / Unable to play. Try again or select another track. | 오디오 요청·재생 실패 상태와 플레이어 모듈 마운트 실패 안내입니다. | "곡을 불러오지 못했습니다. 다시 시도하세요." |
noScript |
请启用 JavaScript 使用播放器。 / Enable JavaScript to use the player. | JavaScript가 꺼졌을 때 noscript 안내이며 네이티브 대체 오디오를 제공하지 않습니다. | "JavaScript를 켜면 플레이어를 사용할 수 있습니다." |
전체 터미널 UI의 보이는 문구 대체표는 아닙니다. PLAY / PAUSE, PREV / NEXT, OPEN / MIN, MUTE / UNMUTE, QUEUE, SHOW / HIDE, TRACKS, LVL, AUDIO CHANNEL, STATE, SIGNAL, STANDBY는 고정 코드입니다. 설정은 접근성 이름 또는 SIGNAL 행의 보이는 상태이므로 버튼이 여전히 영어라고 미적용으로 판단하지 마세요.
한국어 로드·오류 문구만 바꾸는 예시입니다.
i18n: {
locales: {
ko: {
messages: {
music: {
loading: '곡을 불러오는 중',
error: '곡을 불러오지 못했습니다. 다시 시도하세요.',
},
},
},
},
},
언어 활성화·대체는 다국어 가이드를 참고하세요. 문구는 언어를 따르고 곡 목록은 전역 공유입니다.
오디오는 언제 내려받고 왜 기다리나요?
첫 사용이며 저장된 재개 상태가 없다면 UI 초기화는 다운로드하지 않습니다. 재생·이전·다음·목록 곡 클릭으로 선택 곡을 요청합니다. 패널·목록만 열어도 전체 곡을 내려받지는 않습니다. 같은 탭의 재개 상태 복구는 선택 곡을 자동 요청할 수 있습니다.
현재 선택 오디오 전체를 다운로드해 Blob으로 만든 뒤 Audio로 재생합니다. 일부만 받고 시작하는 스트리밍이 아닙니다. 서버가 Range를 무시해도 받은 내용의 위치를 바꿀 수 있지만 큰 파일은 초기 대기·메모리를 늘립니다. 자동 인코딩·압축·다중 비트레이트 생성은 없습니다.
일시정지 후 재생은 현재 오디오·Blob을 재사용합니다. 다른 곡은 미완료 다운로드를 중단하고 이전 자원을 해제하므로 다시 돌아오면 요청할 수 있습니다. 서버·브라우저 HTTP 캐시는 별도이며 전체 곡을 영구 캐시한다는 뜻은 아닙니다. 실패 곡을 자동 건너뛰지 않으며 재생을 눌러 재시도하세요. 재생 권한 거부는 blocked 안내이며 사용자 동작이 필요합니다.
외부 서버는 CORS와 성공 응답이 필요합니다. 프록시, 인증 헤더, 사용자 자격 증명 설정은 없습니다. 같은 사이트 public 오디오는 별도 CORS가 필요 없습니다. 문구 변경으로 경로·권한·형식을 고칠 수 없습니다.
재생·재개·외형: 고정 동작과 설정 범위
| 항목 | 현재 동작 | site.config 필드 여부 |
|---|---|---|
| 기본 곡 | 일치하는 저장 곡이 없으면 첫 곡이며 해석된 src로 매칭합니다. | 아니요, defaultTrack 없음 |
| 기본 음량 | 최초 0.5이며 이후 같은 탭의 음량을 복원할 수 있습니다. | 아니요, defaultVolume 없음 |
| 음소거 | 음량을 0으로 만들고 복원은 기억한 비영 음량입니다. 다운로드·재생을 멈추지 않습니다. | 아니요, 독립 mute 없음 |
| 자동 다음 곡 | 종료 후 다음 항목, 마지막 뒤에는 첫 항목입니다. 무작위가 아닙니다. | 아니요, shuffle / repeat / loop 없음 |
| 재개 | sessionStorage에 주소·위치·음량·접힘·재개 의도를 저장합니다. 같은 탭 탐색·복원 후 시도하며 브라우저 권한 영향을 받습니다. | 아니요, autoplay / resume 없음 |
| 패널 초기 | 표준 컴포넌트는 접힘입니다. 초기 인수가 저장 표시 선호보다 우선하며 BFCache는 별도 상태 복구가 있습니다. | 아니요, theme.music.collapsed 없음 |
| 접기·펼치기·목록 | UI만 바꾸고 재생은 멈추지 않습니다. Escape로 열린 패널을 접습니다. | 아니요, site.config 단축키 없음 |
| 페이지 스타일 | 현재 페이지에 따라 Matrix / Cyber / Hacker / AI / 기본 외형이며 곡 종류로 고르지 않습니다. | 아니요, theme.music.scene 없음 |
| 애니메이션 | Matrix 자체 효과를 재생·페이지 가시성·접힘에 맞춰 실행하고 시스템 동작 줄이기를 따릅니다. 효과 실패가 재생을 막아서는 안 됩니다. | 아니요, 음악 전용 효과 스위치 없음 |
sessionStorage는 세션이며 영구 클라우드 기록이나 탭 간 동기화가 아닙니다. 저장 제한 시 작동은 가능해도 상태 복원은 보장하지 않으며 페이지 간 무중단 재생도 보장하지 않습니다. JavaScript가 없으면 noScript 안내와 함께 상호작용을 사용할 수 없습니다.
컴포넌트·사용자 레이아웃의 initiallyCollapsed, musicInitiallyCollapsed, scene은 공개 site.config 필드가 아닙니다. theme.music에 바로 추가해도 적용되지 않습니다. 표준 페이지는 기본 접힘이며 사용자가 펼칩니다. 곡·제목 문구가 분위기를 자동 전환하지 않습니다.
음악의 두 설정 필드, 세 곡 필드, 열아홉 문구 모두 소비 위치가 있습니다. 추가 호환·중단 필드는 필요 없습니다. 접근성 용도, 고정 영어, 세션 상태를 구분하세요. 설정 사전 시작 페이지에서 다른 모듈을 보세요.