콘텐츠로 이동
quickthumb
전체 문서

Quickthumb 0.8.0

Quickthumb 0.8.0에는 v0.7.0 이후 개발한 기능을 모았습니다. Canvas와 Deck의 공통 출력 API, 더 정밀한 애니메이션, 벡터 경로, 텍스트 선택자, 합성, 제한된 범위의 Lottie 내보내기, 통합 프레젠테이션 UI가 포함됩니다. 아직 1.0 이전 버전이며 하위 호환성이 깨지는 변경이 있습니다. 저장한 명세와 스크립트, 연동 코드를 업데이트하기 전에 마이그레이션 안내를 읽어 주세요.

v0.7.0에서의 마이그레이션으로 이동.

python -m pip install --upgrade "quickthumb[cli]==0.8.0"

Python 3.11 이상이 필요합니다. 비디오 내보내기에는 외부 FFmpeg 설치가 필요합니다. Python 선택 의존성을 설치해도 네이티브 프로그램이나 라이브러리는 설치되지 않습니다.

하나로 통합된 문서와 출력 워크플로

Canvas와 Deck은 이제 validate(), inspect(), diagnose(), prefetch_assets(), sample(), export()를 가진 구조적 Document 프로토콜을 구현합니다. 새 문서 래퍼를 만들 필요가 없습니다.

from quickthumb import Canvas, Deck, VideoOptions

canvas = Canvas(320, 180).background(color="#102030").shape(
    "rectangle", position=(24, 24), width=96, height=64, color="#42CEB7",
)
receipt = canvas.export("card.png")
print(receipt.written_paths, receipt.pixel_metrics.width)
frames = canvas.sample(time=[0.0])
print(frames.frames[0].sha256)
Deck(slides=[canvas]).export("slides.mp4", animation=VideoOptions(hold=1.0))
  • export(path, ...)는 권장 파일 API이며 ExportResult를 반환합니다. 기록한 경로, 지원 기능/대체 출력 진단, 픽셀과 타이밍 측정값, 에셋, 관찰된 렌더링 환경이 포함됩니다. render()도 사용할 수 있지만 확인서를 반환하지 않습니다. 둘 다 공통 파일 옵션과 지원 기능 정책을 적용합니다. 바이트/문자열 to_*() 메서드는 각자의 계약을 유지합니다.
  • sample()은 기준 렌더러의 FrameSequence / CanonicalFrame 데이터를 반환합니다. inspect_document()는 내보내기 파일을 쓰지 않고 레이아웃, 모션, 진단, 관찰한 에셋을 모읍니다.
  • 기준 to_json() / from_json()은 두 문서 종류와 플러그인 참조를 모두 지원합니다. JSON은 작성된 장면을 설명하며 내보낸 프레임, 콜백, 글꼴, 에셋 아카이브가 아닙니다. 보고서 모델에는 model_dump_json()이 있습니다.
  • 구조화된 오류는 입력 경로와 레이어 맥락을 담은 code와 details를 제공합니다. 기존 Quickthumb 오류 타입에 InputError, MissingAssetError, ErrorDetail이 추가됩니다. 검증 및 진단 보고서는 JSON으로 안전하게 표현할 수 있습니다.

일반 파일 출력은 기존 파일을 덮어쓸 수 있습니다. Deck을 래스터 형식으로 내보내면 슬라이드마다 번호가 붙은 파일을 만들고, 저장한 경로를 결과 보고서에 기록합니다. 여러 파일을 한꺼번에 원자적으로 저장하는 트랜잭션은 아닙니다. 알 수 없는 확장자, 호환되지 않는 옵션 계열, 미지원 형식 재정의는 거부합니다. 명시적인 래스터 format 재정의는 지정한 경로 이름을 바꾸지 않고 PNG/JPEG/WebP를 지원합니다. JPEG 품질은 1–95, 일반 WebP 품질은 1–100이며 PNG는 여기서 압축 quality를 받지 않습니다.

출력 계약 · 공개 API · JSON/스키마

애니메이션, 오디오, 렌더링

  • 변환 샘플링은 서브픽셀 아핀 기하를 사용합니다. anchor는 레이아웃 align과 별개인 정규화된 0–1 변환 중심이며 ScaleXTrack과 ScaleYTrack은 독립 축을 추가합니다. 이미지 ScaleTrack은 이제 다른 레이어처럼 외부 개체의 크기를 바꿉니다. ImageZoomTrack과 이미지 팬/Ken Burns 제어는 이미지 뷰포트 내부 콘텐츠를 다룹니다. 정적 변환과 애니메이션 변환 처리가 일치합니다.
  • PositionKeyframeSpec은 Bézier 핸들과 일정 속도 경로 샘플링을 추가합니다. 위치 값은 작성한 배치의 오프셋이며 핸들은 캔버스의 절대 제어점이 아니라 해당 키프레임의 오프셋입니다. 절대 TimingSpec.start 값은 이제 JSON 왕복 변환에서 유지됩니다. auto_orient는 트랙 순서와 관계없이 경로 방향을 작성된 회전/회전 트랙에 더합니다. ColorTrack은 지각적 텍스트/도형 페인트 보간을 사용합니다.
  • CubicBezierEasing, 키프레임별 이징, 유지 키프레임, 닫힌 형태의 SpringEasing, 시드 지정 및 대역 제한 Wiggle로 모션 작성을 확장합니다. 스프링은 끝점이 정확한 정규화된 1초 응답을 사용합니다. Wiggle은 작성된 시작 상태를 보존하며 모션 뒤에는 마지막 흔들림을 고정합니다.
  • Canvas.null() / NullLayer와 parent는 지원 범위 내의 중첩 그룹 합성, 카운터, 클립, 마스크를 포함한 장면 내부 변환 계층을 지원합니다. .group()은 간단한 자동 레이아웃 진입점으로 유지됩니다. 부모 내부 배치가 백분율 좌표를 부모 기준으로 바꾸지는 않습니다. 여전히 캔버스 기준으로 계산합니다. 미지원 합성은 진단합니다.
  • 단어/줄 시차 효과는 배치된 텍스트 레이아웃을 사용합니다. RangeSelector는 가중 선택과 애니메이션 경계를 지원합니다. 문자 대상은 자소 묶음이 아니라 Unicode 코드 포인트입니다. 정확한 조각을 요청하면 단일 대상을 포함해 출력 전에 렌더링하거나 거부하며 근사 분할 경로는 없습니다.
  • quickthumb.audio.analyze_audio()는 캐시된 AudioAnalysis의 소스 시계 기준 온셋 시점과 상대 RMS 구간을 반환합니다. 온셋을 숫자 타이밍 기준점으로 쓰거나 AnimationSpec.timeline()에서 analysis.scale_track()을 사용하세요. 이는 순간적인 변화 감지이며 비트 추적이 아닙니다. 사운드트랙도 자동으로 붙이지 않습니다.
  • 비디오 샘플링은 디코딩된 타임스탬프를 따릅니다. 자막 경계와 인코딩 출력 시계는 기준 장면 시간과 별도로 테스트합니다. 시간은 초 단위입니다. GIF 양자화와 코덱 타이밍은 기준 격자와 다를 수 있습니다. 확인서는 모든 코덱의 시계가 같다고 약속하는 대신 타이밍을 보고합니다.
  • GIF/비디오 프레임 스트리밍, 정적 슬라이드 접두 구간 재사용, 글꼴 페이스 공유, 제한된 spawn 기반 프레임 워커로 반복 작업을 줄입니다. 기본값은 workers=1이며 지원하는 다중 워커 출력은 1–8개를 받습니다. 공간적 슈퍼샘플링에는 render_quality="high"를 사용하세요. 선택적 MotionBlur는 바이트 메서드가 아니라 파일 옵션과 이미지 시퀀스에 시간적 노출을 추가합니다. 공간적 품질과 별개이며 명시적 합성 한계가 있습니다. to_gif()에서도 비례 크기 제한 max_size와 팔레트 colors(2–256)를 지정할 수 있습니다. 이전에는 파일 경계의 GifOptions로만 제공했습니다.

모션과 타이밍 · 오디오 API와 예제 · 키네틱 로어 서드

경로, 마스크, 플러그인

  • Canvas.path() / PathLayer로 고정 뷰포트 안에 SVG 경로 데이터를 작성합니다. 다각형 경로, 적응형 2차/3차 곡선과 타원 호, 지원 범위 내의 그라디언트 채우기, 실선/파선, 선 끝과 연결을 지원합니다. 애니메이션 기하는 장치 해상도에서 다시 그립니다. DashOffsetTrack, TrimStartTrack, TrimEndTrack, TrimOffsetTrack은 기준 경로 길이 샘플링을 사용합니다.
  • PathMorphTrack은 대응하는 경로 윤곽을 보간합니다. 기존 슬라이드 간 transitions.Morph와 다른 API이며 모든 벡터 내보내기가 모프 트랙을 처리한다는 뜻은 아닙니다.
  • TrackMatte는 소스 가시성, 반전, 재사용 규칙을 명시하는 알파/휘도 소스를 지원합니다. 소유자 내부 경로 마스크와 MaskPositionTrack, MaskSizeTrack, MaskFeatherTrack으로 마스킹을 확장합니다. 중첩/동적 그룹, 자막, 배경 및 다른 미지원 조합은 조용히 근사하지 않고 거부합니다. 네이티브 HTML 하드 마스크의 지원 범위는 래스터보다 좁습니다.
  • 버전이 있는 PluginDefinition / PluginRegistry 등록은 매개변수, 에셋, 동기 래스터 콜백을 선언합니다. Canvas.plugin()과 JSON 불러오기는 명시적 레지스트리를 받습니다. 플러그인은 샌드박스가 아니라 신뢰하는 Python 코드이며 JSON은 콜백을 설치하지 않습니다. 래스터 렌더링이 필수입니다. 시간 지정 플러그인과 workers > 1의 플러그인 렌더링은 지원하지 않습니다. 선택적 SVG 훅은 SVG에만 영향을 주며 네이티브 출력으로 쓰려면 로컬 픽셀 비교를 통과해야 합니다.

경로 API · 마스크와 매트 · 플러그인 계약

출력 형식과 한계

출력 0.8.0의 변경 사항
PNG/JPEG/WebP 공통 파일 정책, 확인서, 명시적 품질 검증을 제공합니다. 여전히 래스터 출력입니다.
이미지 시퀀스 export_image_sequence()는 PNG, JPEG, WebP 프레임과 매니페스트를 새 디렉터리에 기록합니다. 기존 디렉터리는 비어 있어도 덮어쓰지 않습니다. 부모 디렉터리가 있어야 합니다. 비공개 스테이징과 배타적 원자적 이름 변경으로 게시합니다. 충돌에도 내구성을 보장하는 에셋 아카이브는 아닙니다. 오디오는 없습니다.
GIF/MP4 공통 애니메이션 시계와 출력 제어를 사용합니다. Deck MP4는 기본적으로 애니메이션을 재생하며 슬라이드별 내레이션과 사운드트랙 일정을 유지합니다. MP4는 불투명하며 GIF에는 팔레트/투명도 한계가 있습니다.
WebM/MOV transparent=True는 VP9 알파 WebM과 ProRes 4444 MOV를 지원합니다. 알파 지원이 코덱 색상 변환이나 재생기에서 RGB/RGBA의 정확한 무손실을 보장하지는 않습니다. MOV에는 FFmpeg의 prores_ks가 필요합니다.
SVG 지원 범위 내의 네이티브 경로/페인트와 허용된 플러그인 라우트를 제공합니다. 확인서는 실제 네이티브 레이어와 래스터 레이어를 구분합니다. 정적 충실도 관찰은 CairoSVG를 사용합니다. Deck to_svg() 메서드는 없습니다.
HTML 프레젠테이션은 대화형입니다. 지원하는 네이티브 경로 선 위상/트림과 하드 마스크 매핑에는 범위 제한이 있습니다. 경로 모션 매핑은 120Hz 샘플링 격자와 작성된 절점을 사용합니다. 미지원 애니메이션은 Deck 슬라이드별 라우트를 포함해 정적/대체 출력을 명시적으로 보고합니다.
PDF 지원 범위의 경로는 편집 가능한 곡선이 되고 미지원 페인트에는 명시적 래스터 대체 출력을 사용합니다. 선택적 PDFium 비교는 실제 실행 라우트를 보고합니다. Deck PDF 충실도 관찰은 거부합니다.
PPTX 확인서는 실제 편집 가능/래스터 라우트를 보고하며 지원 여부는 기능별로 다릅니다. Linux 테스트 모음은 네이티브 PowerPoint 재생/충실도를 인증하지 않았습니다.
Lottie .lot export()/render()와 LottieOptions를 통한 Canvas 전용 출력입니다. Deck이나 바이트 API는 없습니다. 지원 범위의 도형/경로 단색 페인트(알파 포함), 3차 기하, 네이티브 선 트림, 샘플링된 유지 포즈, Null/Shape 부모 계층, 불투명 텍스트 페인트를 쓰는 자체 완결적 정적 ASCII 텍스트 외곽선을 지원합니다. 일반 래스터 대체 출력, 오디오, 이미지, 그라디언트, 임의 텍스트 셰이핑, 트랙 매트, PathMorphTrack 처리는 없습니다. 다른 정책이 래스터화를 요청해도 미지원 기능은 오류가 납니다. 
from quickthumb import ImageSequenceOptions, LottieOptions

canvas.export_image_sequence(
    "frames", format="webp", lossless=True,
    options=ImageSequenceOptions(fps=30.0, hold=1.0),
)
canvas.export("card.lot", animation=LottieOptions(fps=30.0, hold=1.0))

이미지 시퀀스 인코딩 인수는 타이밍과 별개입니다. PNG는 기준 8비트 비연관 RGBA를 보존하고 JPEG는 기본 흰 매트 위에 RGB로 평탄화하며 WebP는 손실 또는 무손실일 수 있습니다. 시퀀스 JPEG/WebP quality는 일반 WebP의 1–100과 달리 1–95입니다. lossless는 WebP 전용이며 호환되지 않는 매개변수는 오류가 납니다. 매니페스트는 언제나 RGBA가 같다고 주장하지 않고 인코딩, 프레임 이름/수/타이밍, 크기, 알파, 모드, quality/lossless/matte를 정확히 기록합니다.

ExportPolicy는 미지원 모션 처리를 명시합니다. 네이티브 라우트 보고서는 실제 선택된 라우트의 관찰 결과이며 모든 뷰어에서 편집 가능하다는 보장은 아닙니다. 선택적 정적 SVG/PDF fidelity 한계는 보고 전용입니다. 한계를 넘었다고 자동 거부하거나 렌더러를 바꾸지 않습니다. Chrome 비교는 테스트 도구이며 새 프로덕션 렌더링 백엔드가 아닙니다. 형식별 한계를 참고하세요.

에셋, 글꼴, CLI, 프레젠테이션

  • 원격 확인을 공유하며 prefetch_assets()와 캐시 상태, 소스/콘텐츠 식별 정보, 오래된 이유를 담은 매니페스트를 추가합니다. 오프라인 캐시 렌더링은 명시적이며 오래된 데이터는 보고하고 자동 거부하지 않습니다. 문서는 첫 원격 확인 결과를 유지하고 새 문서는 현재 캐시 정책으로 다시 확인합니다. 보고서는 바이트를 전달하거나 캐시 수명을 소유하지 않습니다. 내보내기가 끝날 때까지 로컬 파일과 참조한 캐시 파일을 유지하세요. 캐시 제어는 QUICKTHUMB_ASSET_CACHE_DIR, QUICKTHUMB_ASSET_MAX_AGE, QUICKTHUMB_ASSET_OFFLINE입니다.
  • 렌더링 환경은 실제 글꼴 바이트, 페이스/가변/셰이핑 식별 정보, 렌더러 버전을 기록합니다. 원격 글꼴은 콘텐츠 주소 기반 사본을 사용합니다. 기본 QUICKTHUMB_DEFAULT_FONT 선택은 이제 weight, bold, italic을 따르므로 기존 텍스트의 줄바꿈, 정렬, 보이는 픽셀이 달라질 수 있습니다.
  • quickthumb doctor는 발견된 요구 사항과 쓰기 준비 상태를 검사하고 quickthumb inspect는 공통 Canvas/Deck 외부 구조를 제공합니다. 스키마, 린트, 렌더링, 오류 출력은 강화된 문서 계약을 따릅니다. CLI 래스터 품질은 JPEG 1–95 / WebP 1–100 구분을 따릅니다.
  • quickthumb serve는 슬라이드 중심 프레젠테이션을 기본으로 유지합니다. 프레젠테이션과 Inspect motion은 따뜻한 흰색/청록색 UI, 실제 슬라이드 썸네일, 원래 슬라이드 비율을 공유합니다. 모션 패널은 타이밍/프록시 제어로 내보내기 렌더러의 래스터 프레임을 탐색합니다. 재생, 오디오, 편집기가 아닙니다. --timeline은 이 검사 모드를 엽니다. 발표자 보기도 현재/다음 슬라이드, 노트, 경과 시간, 탐색과 함께 테마를 맞춥니다. 키보드/큐 진행, 청중 동기화, 소스 다시 불러오기는 유지됩니다.
  • 설치/문서는 기본 출력과 cli, svg, pdf, pptx, lottie, rembg 선택 의존성을 구분합니다. CairoSVG에는 네이티브 Cairo가 필요합니다. 텍스트 외곽선에는 [lottie]/fontTools와 지원 글꼴이 필요하며 0이 아닌 자간에는 RAQM이 필요합니다. 배경 제거는 처음 사용할 때 모델을 내려받을 수 있습니다.
  • 보안/의존성 유지보수에는 패치된 rembg/ONNX Runtime, Pillow, certifi, filelock/virtualenv, ty 0.0.84와 최신 고정 CI 액션, watchfiles, Typer, inline-snapshot, diff-cover가 포함됩니다. 기존 스캔 게이트는 유지됩니다.

설치 · CLI와 serve · 예제

v0.7.0에서의 마이그레이션

제거된 진입점의 호환성 별칭은 제공하지 않습니다.

이전 0.8.0
deck.to_animated_mp4(slide_duration=2.0) deck.to_mp4(hold=2.0)을 사용합니다. 파일에는 deck.export("out.mp4", animation=VideoOptions(hold=2.0))를 사용합니다.
정적 내레이션 PNG 슬라이드용 deck.to_mp4(...) / deck.render_mp4(...) 일반 MP4가 이제 모션을 재생합니다. 컷에는 정적 캔버스와 명시적 transitions.Cut()을 사용하세요. 내레이션/길이는 .slide()에 유지됩니다. 기존 정지 전용 메서드는 제거되며 조용히 보존하지 않습니다.
deck.to_gif(slide_duration=2.0) / deck.to_webm(slide_duration=2.0) 두 메서드에 hold=2.0을 사용하세요. 저장한 애니메이션 옵션 JSON도 업데이트하세요.
canvas.diagnose() / deck.diagnose() 직접 순회 .diagnose().findings를 순회하세요. DiagnosticReport가 기존 결과 형태를 대신합니다.
deck.model_dump(mode="json") 장면 데이터에는 json.loads(deck.to_json())를 사용하세요. 결과/보고서 모델은 Pydantic 직렬화를 유지합니다.
문서 kind 없는 수동 JSON 또는 알 수 없는 필드/중복 레이어 ID가 있는 JSON 슬라이드를 포함한 문서 경계에 kind: "canvas" / "deck"를 추가하고 레이어 type을 유지하며 잘못된 필드/ID를 수정하세요. 설치한 버전으로 스키마를 다시 생성하세요. 엄격한 파싱은 비유한 수/뒤따르는 JSON과 잘못된 스칼라 필드도 거부합니다.
이미지 ScaleTrack을 뷰포트 확대/축소로 취급 뷰포트 확대/축소에는 ImageZoomTrack을 사용하세요. ScaleTrack은 이미지 외부 기하를 변환합니다. 앵커, 자동 방향 설정과 회전 오프셋을 검토하세요.
quickthumb에서 타임라인/컴파일러/렌더러 헬퍼 임포트 문서화된 작성 타입과 문서 sample() / inspect_motion() 작업을 사용하세요. 저수준 구현 헬퍼는 더 이상 루트 수준 공개 내보내기나 지원되는 수명 주기가 아닙니다.
기본 글꼴 스타일이 보통 페이스를 선택한다고 가정 글꼴/스타일을 명시적으로 선택하고 수정된 스타일 검색 뒤 레이아웃을 검토하세요.

일반 MP4 경로에서 정적 내레이션 컷 시퀀스를 만드는 예제입니다.

from quickthumb import Deck, VideoOptions, transitions

deck = Deck(320, 180, transition=transitions.Cut())
deck.slide(canvas, audio="narration.wav", duration=2.0)
deck.export("narrated.mp4", animation=VideoOptions(fps=30.0, hold=1.0))
mp4_bytes = deck.to_mp4(fps=30.0, hold=1.0)

duration은 내레이션 길이를 재정의합니다. 그렇지 않으면 기본 유지 시간을 사용하기 전에 내레이션이 정적 슬라이드 길이를 제공합니다. 임의의 애니메이션 Canvas를 정지시키는 것은 아닙니다. None 전환은 기존 기본 페이드를 사용하므로 컷에는 명시적 Cut을 사용하세요. 동작 줄이기는 별도 정책입니다.

미출시 중간 체크아웃을 기준으로 만든 연동은 export_png_sequence / PngSequence*를 export_image_sequence / ImageSequence*로, 애니메이션 옵션 quality를 render_quality로, to_narrated_mp4 / render_narrated_mp4를 일반 MP4 경로로 바꾸세요. 중간 내레이션/시퀀스 이름은 v0.7.0 공개 API가 아니었습니다. 몽키패치한 render() 훅은 더 이상 export() 디스패치 수단이 아닙니다.

검증과 남은 한계

릴리스 전 통합 main은 Linux CI에서 테스트 4,632개 통과, 3개 건너뜀, 커버리지 92.23%, 품질/타입/빌드/보안 검사를 통과했습니다. 버전 PR과 게시된 wheel은 릴리스 파이프라인에서 별도로 검사합니다. 문서에 명시된 제한 범위의 Lottie, HTML, 벡터, 타이밍, 알파 라우트에는 기준 재생기와 픽셀 근거가 있습니다. 모든 조합이나 네이티브 애플리케이션을 인증하지는 않습니다.

남아 있는 Linux 기본 글꼴 골든 갱신은 이번 릴리스에서 새로 검증되지 않았습니다. 형식별 구현 및 네이티브 애플리케이션 한계는 위의 각 출력에 명시되어 있습니다.

전체 비교: https://github.com/sjquant/quickthumb/compare/v0.7.0...v0.8.0