FOR DEVELOPERS

앱에 MPDF 연결하기

MPDF는 표준 PDF 첨부파일로 음악 정보를 전달합니다. 기본 형식과 선택 확장을 구분해서 구현하면 기존 PDF 표시 기능을 유지하면서 필요한 재생 기능을 추가할 수 있습니다.

기본 형식: mpdf.json

PDF의 EmbeddedFiles 이름 트리에서 mpdf.json을 읽습니다. MPDF 1.x의 기본 구성은 트랙, 페이지 큐와 재생 옵션입니다. 내장 음원은 별도의 PDF 첨부파일이며 file:로 참조합니다.

mpdf.json · 기본 예시

{
  "mpdf": "1.0",
  "title": "Practice score",
  "tracks": [
    { "id": "backing", "title": "Backing track", "src": "file:backing.m4a", "start": 10, "end": 70 }
  ],
  "cues": [ { "page": 1, "track": "backing", "at": 10 } ],
  "options": { "autoplay": false, "followPage": false, "loop": false }
}

페이지는 1부터 셉니다. start와 end는 원본 음원의 초 단위 위치이며, 큐의 at도 원본 음원의 절대 시각을 사용합니다. 예시에서 at: 10은 원본 음원의 10초를 뜻합니다. 선택 확장의 timeMarkers.seconds는 트랙 시작점에서부터의 상대 시간입니다.

선택 확장: 필요한 만큼 읽고 보존하기

정보	역할
`buttons`	페이지 위 재생 버튼의 위치와 연결된 트랙
`timeMarkers`	페이지 위치와 트랙 내 상대 시간 표시
`seetogether-mpdf.json`	SEETO 제작 정보, 선택 재생 트랙, 제작자 표시, 공유본 상태
`seetogether-score.json`	포함된 카피 노트 악보·코드 재생 데이터
편집용 원본·필기 첨부	제작자 수정용 자료. 공개 공유본에서는 제외

이 확장들은 기본 MPDF 재생의 필수 요건이 아닙니다. 지원하지 않는 필드는 읽을 때 무시하되, 수정본을 만들 때 임의로 삭제하지 마세요. 원본 그대로 다운로드하는 경우는 PDF를 재작성하지 않고 받은 바이트를 그대로 전달합니다. 별도 공유 복사본은 공개할 데이터만 남기는 명시적 내보내기입니다.

읽기와 재생

JavaScript · pdf.js

const pdf = await pdfjsLib.getDocument({ data: bytes.slice() }).promise
const attachments = (await pdf.getAttachments()) || {}
const raw = attachments['mpdf.json']
if (raw) {
  const manifest = JSON.parse(new TextDecoder().decode(raw.content))
  // Validate version, size limits, unique IDs, page ranges and track references.
  // Render text with textContent, never as HTML. Keep unknown extension fields.
  // Resolve file: names against attachments; never treat them as filesystem paths.
  // Retain `bytes` for an unchanged download; rewriting changes the file hash.
}

youtube:는 보이는 공식 YouTube 플레이어, file:는 해당 PDF 첨부, https:는 유효한 외부 음원 URL로 연결합니다. 외부 서버의 CORS·형식·접근 설정에 따라 재생이 제한될 수 있습니다.
사용자가 재생을 시작하기 전에는 자동 재생하지 않습니다. 페이지 큐 따라가기는 사용자 설정을 따릅니다. 큐가 없는 페이지에서는 현재 재생을 이어갑니다.
버튼·마커는 PDF를 덮어쓰지 않는 별도 인터랙션 레이어로 표시합니다. 플레이어는 악보를 가리지 않도록 접거나 화면 밖 영역에 배치합니다.
파일명은 유니코드를 보존하되 경로·예약 메타데이터 이름을 음원으로 허용하지 않습니다. 크기, 페이지 범위, 시간, ID와 참조를 검증합니다.

새 MPDF 만들기

Python · pypdf

from pypdf import PdfWriter
import json

# Create a NEW MPDF from a plain PDF; do not overwrite the input.
w = PdfWriter(clone_from="score.pdf")
w.add_attachment("mpdf.json", json.dumps(manifest).encode("utf-8"))
w.add_attachment("backing.m4a", audio_bytes)
w.write("score-with-music.pdf")

이 예시는 일반 PDF로 새 파일을 만드는 최소 예시입니다. 기존 MPDF를 수정할 때는 중복 이름 트리와 알려지지 않은 첨부·확장을 고려해야 합니다. 저장소의 JavaScript·Python 기본 레퍼런스와 site/mpdf-browser.js의 웹 호환 계층을 구분해 참고하세요.

제작자 표시는 권한 증명이 아닙니다

SEETO 원본 수정은 비익명 계정과 파일 전체의 SHA-256을 사용합니다. 불변 제작자 레지스트리의 파일 해시·발행 ID·소유자 UID가 모두 일치해야 합니다. 메타데이터의 creatorUID만으로 편집을 허용하면 안 됩니다. sharedReadOnly: true는 제작자 본인에게도 읽기 전용입니다. 등록은 완성 파일을 만든 뒤 수행하고, 등록이 성공한 뒤 제공해야 합니다.

공개 링크 서비스는 별도입니다

이 웹사이트의 Cloudflare Pages Functions는 공유용 PDF만 저장합니다. 내장 음원, 편집 원본 및 허용되지 않은 첨부를 거부하고 링크 생성 후 90일이 지나면 제공을 중단합니다. 이 정책과 SEETO 계정 연동은 MPDF 기본 파일 규격의 필수 요소가 아닙니다.

코드 라이선스는 MIT, 사양 문서는 CC BY 4.0입니다. 기술 제안은 GitHub Issues, 비공개 자료·삭제 요청은 지원 이메일을 이용하세요.