chartreel은(는) 무엇을 하나요?
chartreel CLI로 간결하고 정직한 데이터 애니메이션 동영상을 만드세요. 차트를 선택하고, 데이터를 가공하고, 스토리를 작성한 후 렌더링하고 결과를 확인하세요. 렌더러는 CSV의 값 또는 두 인접 행 사이의 선형 보간값만 표시합니다.
0. 도구
chartreel doctor # ffmpeg, Chromium 및 폰트를 확인합니다
chartreel이 없을 경우:
pip install "git+https://github.com/Xkongai/chartreel" # 또는: uv tool install git+https://github.com/Xkongai/chartreel
python -m playwright install chromium # Chrome/Chromium이 이미 설치되어 있으면 건너뜁니다
# ffmpeg: macOS `brew install ffmpeg` · Ubuntu `sudo apt install ffmpeg` · Windows `winget install Gyan.FFmpeg`
# Linux에서 한글/중국어/일본어 텍스트: `sudo apt install fonts-noto-cjk fonts-noto-color-emoji`
1. 실제 데이터를 확보하세요 — 숫자를 절대 임의로 만들지 마세요
- 사용자가 파일을 제공하면 그 파일을 사용하세요. 변경하지 말고 새 CSV로 모양을 바꾸세요.
- 그렇지 않으면 1차 출처에서 데이터를 가져오고 원시 응답을 CSV와 함께 저장하세요.
references/data-sources.md참조 (World Bank API, Our World in Data, FRED, Eurostat, 국가 통계청). - 사용자가 채팅으로 숫자를 입력하면 정확히 그 숫자를 사용하고 "사용자 제공"이라고 출처를 밝히세요.
- 기억에 의존해 빈칸을 채우지 마세요. 빈 셀은 허용됩니다. 내부 빈칸은 보간되며
chartreel validate가 그 개수를 보고합니다. 앞/뒤 빈칸은 해당 계열이 없음을 의미합니다. - 출처 이름, 지표 코드 또는 URL, 라이선스를 기록하고
--source에 포함하세요.
2. 템플릿을 선택하세요
| 스토리 | 템플릿 | 데이터 형태 |
|---|---|---|
| 시간에 따른 1위와 추월 ("GDP 순위 1990–2024") | race | 기간 × 계열 (5–40개 계열) |
| 몇 가지 항목의 성장 또는 교차 ("중국 vs 인도 인구") | line | 기간 × 계열 (2–8개 계열) |
| 놀라운 숫자 하나와 "×N" 비교 ("1910억 달러에서 18.7조 달러로") | counter | label,value[,note] (2–5행) |
| 전체의 분할과 이동 ("지역별 세계 인구") | share | 기간 × 부분 (2–10개 부분, 음수 불가) |
3. CSV 모양을 만드세요
year,China,India,United States # wide: 첫 번째 열 = 기간, 계열당 한 열
1990,361560229446,320979026420,5963144000000
year,name,value # long: 허용됨, 자동 피벗
1990,China,361560229446
label,value,note # counter
1980년,191487500000,改革开放初期
규칙: 기간 오름차순, 일반 숫자 (쉼표, $, %는 제거됨), UTF-8 (BOM 허용). 긴 범위의 경우 연간 행을 유지하세요. 더 많은 행이 더 부드럽고 정확한 움직임을 만듭니다.
4. 데이터 스토리를 작성하세요
- 훅 (제목): 질문 또는 놀라운 점, 2줄 이하. "세계 최대 경제국, 1990–2024", "中印人口之争".
- 컨텍스트 (부제목): 단위와 범위 — "GDP, 현재 US$".
- 주요 순간 (
--note "PERIOD: text"): 1–3개 이벤트. 각 이벤트는 해당 기간의 데이터에서 확인 가능해야 합니다 ("X가 Y를 추월"이라고 쓰기 전에 CSV를 확인하세요). - 핵심 메시지 (
--takeaway): CSV에서 계산된 한 문장. 코드로 연산을 수행하세요. 예:python -c "print(18729668435848/361560229446)"→ 51.8 → "중국 GDP는 34년 동안 52배 성장했습니다". 정직하게 반올림하세요. - 출처 (
--source): 항상 포함하세요. 예:World Bank WDI (NY.GDP.MKTP.CD), CC BY 4.0.
모든 것을 JSON 구성 파일에 넣어 렌더링이 재현 가능하도록 하세요 (references/options.md에 모든 키가 나열됨):
{
"template": "race", "theme": "dark", "aspect": "9:16", "duration": 15,
"title": "세계 최대 경제국, 1990–2024", "subtitle": "GDP, 현재 US$",
"source": "World Bank WDI (NY.GDP.MKTP.CD), CC BY 4.0",
"takeaway": "중국 GDP는 34년 동안 52배 성장했습니다", "prefix": "$", "top": 10,
"notes": ["2010: 중국이 일본을 추월"],
"series": {"중국": {"emoji": "🇨🇳", "color": "#FF6B6B"}}
}
중국어 동영상: "locale": "zh"를 추가하고 (숫자는 만/억/조) 제목과 노트를 중국어로 작성하세요.
4b. 스타일 프리셋을 선택하세요 (선택 사항, 소셜 동영상에 권장)
--style은 테마, 훅 카드, 연도 카운터, 1위 장식 및 효과를 묶습니다. 모든 프리셋은 숫자를 정확하게 유지합니다. 훅은 데이터가 움직이기 시작하기 전인 처음 약 1.5초만 덮고, 핵심 메시지나 (레이스의 경우) 막대 사이에는 아무것도 그리지 않습니다.
--style | 모양 | 적합 |
|---|---|---|
classic (기본값) | 깔끔하고, 훅 없음 | 문서, 슬라이드, X |
cinematic | 금색에 청록색, 레터박스 훅, 비네트, 회전하는 연도, 1위 왕관, 줌인 | YouTube 쇼츠, 빌리빌리 |
news | TV 자막: "DATA" 훅 자막, 순위 번호, 빨간색 연도 배지, 출처 자막 | 진지한 주제, 웨이보/X |
editorial | 종이, 타자기 훅, 회색 막대 + --highlight "A,B", 큰 세리프 연도 | 샤오홍슈, 뉴스레터 |
arcade | 네온, 컨페티 + 막대가 상위 3위 안에 들 때 펀치, 순위 상승 ▲, 속도 줄무늬 | 더우인/틱톡, 게임 |
retro | VHS: 스캔라인, 색수차 텍스트, PLAY 스탬프, 타자기 훅 | 향수 주제 |
glass | 떠다니는 색상 블롭, 프로스트 차트 패널, 상단 진행 막대 | 기술/제품 주제 |
bold | 더우인 큰 텍스트: 거대한 강조 훅 단어, 큰 연도, 순위 번호 | 더우인/콰이쇼우 |
프리셋과 함께 사용하는 스토리 옵션:
--hook "세계 최대 경제국은 누구인가?": 첫 1~2초 동안의 질문 (기본값은 제목,--no-hook으로 끄기). 데이터에서 답할 수 있어야 합니다.--cta "더 많은 데이터 스토리를 팔로우하세요": 핵심 메시지 아래 작은 줄.- 세부 조정:
--fx bg,vignette,letterbox,scanlines,punch,confetti,trails,arrows,glass는 프리셋의 효과를 대체하고,--no-fx confetti는 하나를 제거합니다.--year-style watermark|roll|row|badge,--progress timeline|top|both|none,--highlight leader|"A,B",--leader/--no-leader,--ranks,--safe-zone/--no-safe-zone(프리셋은 더우인/쇼츠 버튼 및 캡션 영역을 피합니다).chartreel styles가 모든 것을 나열합니다. --audio music.mp3 [--audio-fade 1.0]는 사용자가 소유하거나 라이선스를 보유한 트랙을 MP4에 넣습니다 (잘라내고, 페이드 인/아웃). 저작권이 있는 음악을 다운로드하지 마세요; chartreel은 음악을 제공하지 않습니다.
명령줄에 --style을 전달하면 구성 파일의 "theme"은 무시됩니다 (--theme으로 재정의 가능).
5. 검증, 렌더링, 확인
chartreel validate data.csv -c story.json # 스키마 + 옵션 검사, 명확한 행/열 오류 표시
chartreel render data.csv -c story.json -o out/ # out/data.mp4, out/data.gif, out/data-cover.png 생성
chartreel preview data.csv -c story.json -o out/ # 선택 사항: 자체 포함 HTML 플레이어로 스크러빙
플랫폼 프리셋: 더우인/틱톡/쇼츠/릴스 -a 9:16 -d 15 (10–30초) · 샤오홍슈 -a 3:4 또는 9:16 ·
빌리빌리/유튜브/X -a 16:9 · X/인스타그램 피드 -a 1:1 또는 4:5. 페이스: 레이스의 경우 기간당 약 0.3–0.6초.
빠른 초안: --size 540 --fps 15. --jobs N은 병렬 작업자 수를 설정합니다. 12초 1080×1920 레이스는
CPU에 따라 약 10–30초 내에 렌더링됩니다.
그런 다음 출력을 확인하세요:
ffmpeg -v error -i out/data.mp4 -vf "fps=1,scale=360:-1,tile=4x3" -frames:v 1 out/contact.png
커버와 콘택트 시트를 여세요. 확인할 사항: 제목이 잘리지 않음, 레이블 읽기 가능, CJK 토후 상자(□) 없음, 핵심 메시지가 숫자와 일치함, 출처가 보임, 훅(첫 1초)이 한눈에 읽힘. 필요한 경우 수정하고 다시 렌더링하세요.
6. 전달
MP4, GIF 및 커버 경로, 출처와 라이선스, 핵심 메시지가 계산된 방식을 보고하세요. 보간된 셀이 있으면 명확히 말하세요 (validate가 출력함). 데이터가 보여주지 않는 추세를 주장하지 마세요.
정확성 규칙 (협상 불가)
- 화면상 값 = 각 기간의 CSV 값, 그 사이는 선형 보간. 카운터 템플릿은 각 값까지 세고 정확한 숫자를 유지합니다. 질문을 받으면 그렇게 말하세요.
- 파생 숫자 (비율, 성장, "추월")는 CSV에서 계산되어야 하며, 기억에 의존하지 마세요.
- 하나의 차트에서 단위나 통화를 혼합하지 마세요. 명목 값과 실질 값을 조용히 비교하지 마세요.
- 항상 출처를 표시하세요. 원시 다운로드를 보관하여 사용자가 감사할 수 있도록 하세요.