.pptx는 파워포인트에서 텍스트·색·도형을 직접 편집할 수 있다. 핵심은 두 가지다 — (1) 7개 AI 역할(Strategist·Executor·Optimizer…)이 협업해 디자인 규격→SVG→발표 노트를 만들고, (2) python-pptx 위에 직접 쌓은 SVG→OOXML 변환기가 이미지가 아니라 네이티브 도형을 찍어낸다. (저장소: hugohe3/ppt-master · MIT · 스타 28k+ · Python 85% / JavaScript 8% / HTML 3.5%)이 레포가 무엇을 하는 물건인가.
보통의 AI PPT 도구는 슬라이드를 한 장의 그림(PNG)으로 만들어 끼운다. 보기엔 그럴듯하지만, 오타 하나 고치려 해도 손댈 수가 없다. ppt-master는 슬라이드를 먼저 SVG(벡터 도형)로 설계한 다음, 그 SVG의 사각형·원·경로·글자·이미지를 OOXML 도형(<p:sp>, <p:pic>)으로 하나하나 변환한다.
그래서 결과 .pptx를 파워포인트에서 열면 — 텍스트는 텍스트 상자, 도형은 도형, 색은 색으로 살아 있다. "AI가 만들었지만 사람이 끝까지 고칠 수 있는 슬라이드"가 이 레포의 정체성이다.
ppt-master는 문서→편집 가능한 PPTX 생성 파이프라인이다. 입력은 PDF·웹페이지·마크다운·DOCX·XLSX·기존 PPTX 등 무엇이든 좋다. AI 편집기(Claude Code 권장) 안에서 동작하며, 약 7개 AI 역할이 단계별로 협업한다 — 전략가(Strategist)가 8가지 항목을 확정하고 디자인 규격을 세우면, 실행자(Executor)가 슬라이드를 SVG로 연속 생성하고 발표 노트를 쓴다. 마지막으로 파이썬 후처리(finalize_svg.py → svg_to_pptx.py)가 SVG를 네이티브 DrawingML PPTX로 굳힌다.
지원 포맷은 PPT 16:9뿐 아니라 샤오훙수(小红书)·모먼트 카드 등 10종 이상이다. 공식 예시 라이브러리에 21개 프로젝트(지속 추가 중)가 들어 있어, "실제로 어떤 결과가 나오는지"를 GitHub Pages 뷰어로 바로 확인할 수 있다.
<rect>(사각형)·<circle>(원)·<path>(자유 곡선)·<text>(글자) 같은 태그로 그림을 그린다. ppt-master는 AI가 슬라이드 디자인을 SVG로 표현하기 쉽다는 점을 노린다 — LLM은 픽셀을 못 그리지만, "여기에 파란 사각형, 저기에 글자"를 XML로 쓰는 건 잘한다.이미지형 슬라이드 생성기 대비 '진짜 편집' 장점.
2026년 AI 슬라이드 시장은 포화 상태다. Gamma, MagicSlides, Tome, Beautiful.ai… 다 "프롬프트 넣으면 예쁜 슬라이드"를 약속한다. 그런데 막상 회사에서 쓰려고 하면 같은 벽에 부딪힌다 — "브랜드 폰트로 바꿔야 하는데", "이 숫자 하나만 고치면 되는데" 손댈 수가 없다. 결과물이 사실상 이미지거나, 자체 웹 에디터에 갇혀 있어서다. ppt-master가 주목받는 이유는 정확히 이 지점을 푼다는 데 있다.
| 비교 항목 | 이미지형 생성기 (Gamma·MagicSlides 류) | ppt-master |
|---|---|---|
| 결과물 형태 | 이미지 슬라이드 / 자체 웹 문서 | 네이티브 .pptx (DrawingML 도형) |
| 편집 자유도 | 벤더 에디터 안에서만, 제한적 | 파워포인트에서 글자·도형·색 직접 수정 |
| 오프라인 / 소유 | SaaS 종속, 구독 필요 | 로컬 실행, 파일은 100% 내 것 |
| 디자인 엔진 | 블랙박스 템플릿 | SVG + CRAP 디자인 원칙 + MBB 컨설팅 스타일 |
| 입력 다양성 | 주로 텍스트/개요 | PDF·URL·MD·DOCX·XLSX·PPTX |
| 커스터마이즈 | 벤더가 정한 범위 | 역할 프롬프트·템플릿·도구 모두 오픈소스 |
AI가 슬라이드를 통째로 PNG/JPEG로 렌더링하면, 발표 직전에 "한 글자만 고치자"가 불가능하다. 폰트를 회사 표준으로 바꾸지도, 도형을 살짝 옮기지도 못한다. 결국 사람이 다시 처음부터 파워포인트로 만들거나, 벤더 구독에 평생 묶인다. '생성'은 됐는데 '소유'와 '수정'이 안 되는 것이 이미지형 도구의 근본 한계다.
슬라이드를 SVG로 설계하면 모든 요소가 명시적 객체(사각형·원·글자·이미지)로 남는다. svg_to_pptx의 네이티브 변환기가 이 객체들을 DrawingML로 1:1 번역하므로, 결과 PPTX는 파워포인트가 이해하는 편집 가능한 도형이 된다. 게다가 텍스트는 여러 줄을 하나의 편집 가능한 텍스트 프레임으로 병합해(줄 간격·문단 간격까지 보존) "박스를 늘리면 글이 다시 흐르는" 진짜 텍스트 상자로 만든다.
의외로 표준 라이브러리 위주, 핵심은 python-pptx 한 줄.
이 레포의 스택은 두 층으로 나뉜다 — ① 사람이 쓰는 AI 역할(프롬프트) 층과 ② 파이썬 도구(코드) 층. 흥미로운 점은, 도구 대부분이 파이썬 표준 라이브러리만으로 돌아가고 외부 의존성은 "필요할 때만 설치하는 선택지"로 잘게 쪼개 둔 것이다.
| 구성요소 | 역할 |
|---|---|
| 실행 환경 | Claude Code(권장) / Cursor / VS Code+Copilot 등 AI 코딩 편집기. Opus 계열 모델 추천(긴 컨텍스트). |
| 역할 정의 | roles/ + AGENTS.md·CLAUDE.md·GEMINI.md — 7개 AI 역할의 행동 규칙을 마크다운으로 명시 |
| Strategist | 전략가: 템플릿 사용 여부 + 8가지 확인(포맷·페이지 수·청중 등) → 디자인 규격 산출 |
| Executor (3종) | 실행자: General(범용)·Consultant(컨설팅)·Consultant_Top(MBB급) — SVG 페이지 + 발표 노트 생성 |
| Image_Generator | 이미지 생성사: AI 생성 선택 시 gemini-3.1-flash-image-preview(Gemini, 기본값) 등으로 삽화 생성 |
| Optimizer_CRAP | 최적화사: 초안이 미흡할 때 CRAP 디자인 원칙(대비·반복·정렬·근접)으로 핵심 페이지 개선 |
| Template_Designer | 템플릿 설계사: /create-template 워크플로로 새 레이아웃 제작 |
| 분류 | 대표 도구 · 의존성 |
|---|---|
| 소스→마크다운 | pdf_to_md.py(PyMuPDF)·doc_to_md.py(mammoth)·excel_to_md.py(openpyxl)·ppt_to_md.py·web_to_md.py(requests·bs4·curl_cffi) |
| 프로젝트 관리 | project_manager.py init / import-sources / validate |
| SVG 파이프라인 | total_md_split.py → finalize_svg.py → svg_to_pptx.py |
| 핵심 변환 | python-pptx ≥ 0.6.21 — 단, 네이티브 모드는 python-pptx 위에 직접 작성한 DrawingML 생성기로 OOXML을 찍는다 |
| 이미지/수식 | image_gen.py(google-genai)·latex_render.py·fix_image_aspect.py(Pillow·numpy)·gemini_watermark_remover.py |
| 발표 보조 | notes_to_audio.py(edge-tts로 페이지별 내레이션) · svg_editor/server.py(flask 로컬 편집기) |
| 레거시(이미지 폴백) | Office 구버전용 PNG 폴백: cairosvg(권장) 또는 svglib+reportlab |
.pptx·.docx가 내부적으로 쓰는 XML 규격 — pptx는 사실 XML 묶음을 zip으로 압축한 것이다. DrawingML은 그중 도형·텍스트·그림을 기술하는 부분(<p:sp> 도형, <p:pic> 그림, <a:p> 문단). python-pptx는 이 zip+XML을 파이썬 객체로 다루게 해 주는 라이브러리. ppt-master는 단순히 python-pptx의 고수준 API만 쓰는 게 아니라, SVG를 정밀하게 매핑하려고 DrawingML XML을 직접 생성한다.ppt-master를 '번역 출판사'로 보자. 작가(LLM)는 SVG라는 언어로 원고를 쓴다. 번역가(svg_to_pptx)는 그 원고를 파워포인트라는 독자가 읽을 수 있는 DrawingML로 한 문장씩 옮긴다. 단순히 원고를 스캔해 사진으로 끼우는(=이미지형 도구) 게 아니라, 실제 활자로 다시 조판하기 때문에 독자가 오타를 직접 고칠 수 있는 것이다.
문서→개요→SVG→OOXML 파이프라인 + 핵심 설계 패턴.
원본 문서가 들어오면 먼저 마크다운으로 정규화된다(모든 입력을 한 형식으로 통일). 그 뒤 AI 역할들이 디자인 규격→SVG→노트를 만들고, 마지막에 파이썬 후처리가 SVG를 네이티브 PPTX로 굳힌다. 핵심은 "AI는 SVG까지만, 도형 변환은 결정론적 코드가" 맡는 명확한 분업이다.
왜 곧장 PPTX를 만들지 않고 SVG를 거칠까? LLM은 픽셀을 못 그리고, OOXML을 직접 쓰게 하면 너무 장황하고 오류가 잦다. 반면 SVG는 LLM이 자연스럽게 잘 쓰는 선언적 그래픽 언어다. 그래서 ppt-master는 SVG를 중간 표현(intermediate representation)으로 두고, "창의적 디자인은 LLM이 SVG로, 기계적 변환은 코드가 OOXML로"라는 책임 분리를 만든다. 이렇게 하면 같은 SVG로 웹 미리보기(브라우저)와 네이티브 PPTX를 동시에 뽑을 수 있다(2-소비자 구조).
svg_to_pptx는 한 덩어리 스크립트가 아니라 역할별로 쪼갠 패키지다. SVG 태그를 받아 DrawingML로 디스패치하는 변환기, 경로(path) 데이터를 베지에로 푸는 모듈, 스타일/색·그라디언트 처리, 그리고 PPTX 골격(슬라이드 XML·미디어·노트·내레이션)을 조립하는 빌더가 분리돼 있다.
| 모듈 | 책임 |
|---|---|
| drawingml_converter | SVG → DrawingML 디스패처. <g> 그룹 처리 + 변환 실패 시 명시적 에러 |
| drawingml_elements | rect·circle·path·text·image 각각을 <p:sp>/<p:pic>로 변환 |
| drawingml_paths | SVG path d-속성을 DrawingML 커스텀 지오메트리로 번역 |
| drawingml_styles | fill·stroke·그라디언트·효과(그림자 등)를 <a:solidFill>/<a:ln>로 |
| tspan_flattener | <tspan> 평탄화 + 문단 병합 판정(같은 x, 일정 dy 묶음) |
| pptx_builder / _slide_xml | 슬라이드 XML 조립 · [Content_Types].xml 동적 생성 |
| pptx_media | 이미지를 콘텐츠 해시 파일명으로 저장 → 동일 이미지 자동 재사용 |
| pptx_notes / _narration | 발표 노트 임베드 · edge-tts 내레이션·자동 넘김 타이밍 |
SVG의 <text>는 보통 줄마다 <tspan>으로 쪼개진다. 이걸 그대로 변환하면 12줄짜리 문단이 12개의 텍스트 상자가 돼 편집이 끔찍해진다. ppt-master는 같은 x좌표에 일정한 줄 높이로 쌓인 tspan들을 하나의 편집 가능한 텍스트 프레임으로 병합하고, 줄 간격(<a:lnSpc>)·문단 간격(<a:spcBef>)을 정확히 보존한다. 그래서 박스를 늘리면 글이 다시 흐른다. 반대로 표지·차트처럼 정밀 정렬이 필요한 페이지는 --no-merge로 줄 단위를 그대로 유지할 수 있다.
엄격한 실패(fail-loud): 표현할 수 없는 SVG 요소가 있으면 조용히 버리지 않고, 파일명·태그·위치를 찍으며 변환을 중단한다.
원자적 쓰기: 임시 파일에 먼저 쓰고 변환 성공 후에만 최종 PPTX로 교체 — 실패해도 기존 출력이 망가지지 않는다.
SVG 백업: backup/에 Executor의 SVG 원본을 항상 남겨, LLM을 다시 돌리지 않고 finalize_svg → svg_to_pptx만으로 재빌드할 수 있다.
변환기는 최상위 <g id="..."> 그룹을 z-순서대로 훑어 요소별 등장 애니메이션을 자동 부여한다. 단, id에 background·header·footer·watermark 같은 토큰이 든 '페이지 장식'은 자동 제외한다. id 의미에 따라 차트→wipe, 카드→fly, 이미지→zoom 식으로 효과를 매핑하며, 시작 방식(클릭/자동 연쇄)도 PowerPoint의 Start 드롭다운처럼 고를 수 있다.
'레포 루트'와 '실제 엔진'은 다른 곳에 있다.
처음 클론하면 헷갈리는 지점이 있다 — 루트의 tools/·roles/는 사용자 친화 진입점이고, 실제 변환 엔진과 전체 의존성·템플릿은 skills/ppt-master/ 안에 들어 있다(스킬 하나만 설치해도 전 기능이 돈다는 설계). 아래는 레포 전체와, 엔진이 사는 스킬 디렉토리를 함께 그린 것이다.
① 루트 README.md로 흐름 잡기 → ② roles/로 7개 역할이 무엇을 하는지 → ③ skills/ppt-master/scripts/svg_to_pptx/의 drawingml_elements.py를 열어 "SVG <rect>가 어떻게 <p:sp>가 되는가"를 직접 추적 → ④ examples/의 실제 SVG를 보며 결과 체감.
이 레포에서 무엇을 배우고, 무엇을 실습할까.
대부분의 개발자는 python-pptx의 고수준 API(slide.shapes.add_textbox 등)까지만 안다. ppt-master는 그 아래 DrawingML XML을 손으로 짜는 영역까지 내려간다. <p:sp>(도형)·<a:prstGeom>(미리 정의된 도형)·<a:custGeom>(자유 경로)·<a:p>(문단)의 구조를 읽으면, "오피스 파일이 사실 zip+XML"이라는 사실이 손에 잡힌다.
unzip deck.pptx), ppt/slides/slide1.xml을 열어 <p:sp> 하나의 구조를 분석해 보라.SVG는 픽셀(px) 좌표, PPTX는 EMU(English Metric Unit, 1px≈9525EMU) 좌표를 쓴다. 변환기는 transform 행렬을 파싱하고, path의 베지에 곡선을 DrawingML 지오메트리로 다시 푼다. 좌표계 변환·행렬·곡선 수학을 실전으로 배우기 좋은 코드다.
drawingml_utils.py의 EMU_PER_PX와 parse_transform_matrix를 읽고, "회전된 사각형"이 어떻게 좌표 변환되는지 손으로 따라가 보라."LLM에게 최종 산출물을 직접 만들게 하지 말고, 검증·변환 가능한 중간 형식까지만 시켜라"는 패턴은 어디에나 통한다(코드 생성·문서 생성·데이터 파이프라인). ppt-master는 그 교과서적 예시다 — 창의는 LLM, 정확은 결정론적 코드.
PDF·웹·DOCX·XLSX·PPTX를 모두 한 가지 중간 형식(마크다운)으로 통일하는 어댑터 패턴. 입력이 늘어도 다운스트림(LLM·SVG 생성)은 안 바뀐다. source_to_md/ 한 폴더가 "확장에 열린 설계"의 모범이다.
source_to_md/에 새 입력(예: .txt 또는 RSS)을 마크다운으로 바꾸는 변환기를 하나 추가해 보라.'읽기/실습'엔 가볍게, '풀파워'엔 키 몇 개.
| 목적 | 필요한 것 |
|---|---|
| 기본 실행 | Python 3.10+ + pip install -r requirements.txt. 핵심은 python-pptx 하나. |
| AI 슬라이드 생성 | AI 코딩 편집기(Claude Code 권장, Opus 계열). 긴 컨텍스트가 품질을 좌우. |
| PDF/문서 변환 | PyMuPDF(PDF)·mammoth(DOCX)·openpyxl(XLSX) — 필요한 것만 설치 |
| AI 삽화 생성(선택) | GEMINI_API_KEY 환경변수 + google-genai → gemini-3.1-flash-image-preview 호출(기본값, .env의 GEMINI_MODEL로 교체 가능). 프록시는 GEMINI_BASE_URL |
| 웹페이지 변환(고방어 사이트) | curl_cffi(TLS 지문 우회) 또는 Node.js 18+(web_to_md.cjs) |
| 음성 내레이션(선택) | edge-tts(기본, 무료) 또는 클라우드 TTS(elevenlabs·minimax 등) + ffprobe |
| Office 구버전 호환 | SVG→PNG 폴백용 cairosvg(권장) 또는 svglib+reportlab |
| 편집 시 주의 | 내보낸 PPTX 편집은 Office 2016 이상 권장(우클릭 "도형으로 변환") |
ppt-master는 버튼 하나로 끝나는 웹 서비스가 아니라, AI 코딩 편집기 안에서 사람이 대화하며 단계별로 진행하는 워크플로다. 8가지 확인에 답하고, 필요하면 템플릿을 고르고, 초안을 보고 최적화를 돌린다. 그 대가로 결과 파일을 100% 소유하고 끝까지 직접 편집할 수 있다 — 속도가 아니라 통제권을 사는 도구다.
난이도별 5단계 — 사용에서 엔진 내부까지.
레포를 클론하고 examples/의 프로젝트 하나를 골라 GitHub Pages 뷰어로 본다. 그 다음 같은 프로젝트의 svg_output/ SVG 한 장을 브라우저로 직접 열어, "이게 슬라이드가 SVG로 그려진 모습"임을 눈으로 확인한다.
pip install -r requirements.txt 후, pdf_to_md.py로 짧은 PDF를 마크다운으로 변환 → project_manager.py init ... --format ppt169 → AI 편집기에서 Strategist 8항목에 답 → Executor가 SVG 생성 → finalize_svg.py → svg_to_pptx.py. 나온 .pptx를 파워포인트에서 열어 글자를 직접 고쳐 본다.
svg_to_pptx/drawingml_elements.py의 convert_rect()를 읽고, 직접 만든 1줄짜리 SVG(<rect> 하나)를 변환해 본다. 결과 .pptx를 unzip해 slide1.xml에서 대응되는 <p:sp>를 찾아, "SVG 좌표가 EMU로 어떻게 바뀌었나"를 계산기로 검산한다.
여러 줄 본문이 있는 SVG를 만들어 svg_to_pptx.py를 기본(병합)과 --no-merge 두 번 돌린다. 파워포인트에서 텍스트 상자 개수와 "박스 늘렸을 때 글이 다시 흐르는지"를 비교해, tspan_flattener.py의 병합 판정 조건(같은 x·일정 dy)이 왜 그렇게 짜였는지 설명해 본다.
현재 미지원이거나 단순 처리되는 SVG 기능 하나(예: 특정 그라디언트, <polyline> 점선)를 골라, drawingml_elements.py/drawingml_styles.py에 변환 로직을 추가한다. 네이티브 모드의 "표현 불가 시 명시적 실패" 원칙을 깨지 않도록, 지원 못 하는 경우는 분명한 에러를 내게 유지할 것.
6주 코스 — 사용법에서 OOXML 엔진 개조까지.
| 주차 | 주제 | 실습 · 참고 |
|---|---|---|
| 1주차 | 전체 워크플로 + 7개 AI 역할 이해 | README · roles/README.md · docs/workflow_tutorial.md |
| 2주차 | SVG 기초(좌표·viewBox·rect/path/text) + 디자인 원칙(CRAP) | examples/ SVG 정독 · docs/design_guidelines.md |
| 3주차 | OOXML/DrawingML 구조 — .pptx를 zip으로 풀어 분석 | python-pptx 문서 · slide XML 해부 |
| 4주차 | SVG→DrawingML 변환기 코드 리딩(rect→sp, path→custGeom) | drawingml_converter / _elements / _paths |
| 5주차 | 텍스트 문단 병합·좌표 변환·EMU 단위 · 미디어 해시 | tspan_flattener · drawingml_utils · pptx_media |
| 6주차 | 입력 정규화 어댑터 + 자동 애니메이션/내레이션 확장 | source_to_md/ · notes_to_audio.py · animation_config |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| PPTX (네이티브) | 파워포인트 발표 파일. ppt-master 출력은 각 페이지가 이미지가 아니라 편집 가능한 DrawingML 도형으로 채워진다. |
| OOXML | Office Open XML. .pptx/.docx 내부 규격 — XML 묶음을 zip으로 압축한 형태. |
| DrawingML | OOXML 중 도형·텍스트·그림을 기술하는 부분. <p:sp>(도형)·<p:pic>(그림)·<a:p>(문단). |
| python-pptx | OOXML pptx를 파이썬으로 다루는 라이브러리. ppt-master는 그 위에서 DrawingML XML을 직접 생성. |
| SVG | 벡터 그래픽 XML. LLM이 슬라이드 디자인을 표현하는 중간 형식(IR)으로 쓰인다. |
| IR (중간 표현) | 입력과 최종 출력 사이의 다루기 쉬운 중간 형식. 여기선 SVG가 그 역할. |
| prstGeom / custGeom | 각각 '미리 정의된 도형'(사각형·원…)과 '자유 경로 도형'. SVG rect/circle→prstGeom, path→custGeom. |
| EMU | English Metric Unit. PPTX의 길이 단위(1px≈9525EMU). SVG px좌표를 EMU로 변환. |
| tspan 평탄화 | SVG 텍스트의 줄별 <tspan>을 하나의 편집 가능한 문단으로 병합하는 처리. |
| CRAP 원칙 | Robin Williams의 디자인 4원칙: 대비(Contrast)·반복(Repetition)·정렬(Alignment)·근접(Proximity). Optimizer가 적용. |
| Strategist / Executor | 전략가(디자인 규격 확정) / 실행자(SVG·노트 생성). ppt-master의 핵심 AI 역할. |
| finalize_svg / svg_to_pptx | SVG 후처리(아이콘·이미지 임베드 등) / SVG→네이티브 PPTX 변환. 결정론적 파이썬 단계. |
| 콘텐츠 해시 미디어 | 이미지를 내용 해시로 파일명을 매겨, 동일 이미지는 재사용하고 다른 이미지는 덮어쓰지 않게 하는 기법. |
| Gemini 이미지 모델 | 현재 기본값은 gemini-3.1-flash-image-preview. image_gen.py로 슬라이드 삽화 생성에 활용(선택). .env의 GEMINI_MODEL로 교체 가능. |