Skip to content
hyperdrivebeepPublic

About

Duvi · 두 언어로 배우는 로컬 강의 플레이어 — MIT, YouTube, and contextual Korean subtitles.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Duvi · 듀비

영어와 한국어 자막을 함께 보며 강의를 공부하는 로컬 웹앱입니다. MIT OpenCourseWare와 YouTube 강의를 한 라이브러리에서 재생하고, 문장별 이동·반복·자동 멈춤·이어보기를 지원합니다.

학습 시작하기

처음이라면 화면 캡처로 한 단계씩 따라 하는 Duvi로 공부하는 법부터 보세요.

첫 화면의 학습 로드맵 → MIT 1강 시작하기를 누릅니다. 첫 본강의는 MIT Python 기초의 Lecture 1 → 2 → 3 순서입니다. 로드맵에는 단계별 자료와 첫 2주 실습이 있고, 순서대로 강의 폴더 준비로 해당 자료를 라이브러리에 묶습니다.

영상을 보다 막히면 영상 옆 질문하기(일반 화면과 전체화면 모두)에 물어보세요. ChatGPT를 쓰듯 답이 글자로 바로 흘러나오고, 이어서 더 물을 수 있습니다. 답을 만들 때 지금 시점 앞뒤 1분 대본(한국어 번역 포함), 이 강의의 내 기록, 같은 대화의 이전 질문을 함께 보냅니다. Enter는 보내기, Shift+Enter는 줄바꿈, 멈추기는 답변 중단(받은 부분은 저장)입니다. 보낼 때 영상이 멈추며(체크로 끌 수 있음), 답 속 10:14 같은 시각을 누르면 그 장면으로 이동합니다. 대화는 강의별로 이 PC에 남고, 기록으로 저장을 누르면 질문과 AI 답변이 학습 기록이 되어 내 기록 → 열린 질문과 다음 날 복습에 나타납니다. 답을 받으려면 설정에서 ChatGPT를 연결해야 하며(번역과 같은 연결), 답은 AI 제안이므로 원문과 함께 확인하세요.

강의 옆 기록 탭에서는 영어 자막이 있는 시점을 골라 질문 한 줄이나 내 설명을 직접 저장합니다. 근거·가정·대안·예측·실제 결과·바뀐 생각은 선택 입력입니다. 저장한 기록은 내 기록, 예정된 회상은 복습에서 열고 Markdown으로 내려받을 수 있습니다. 최초 설명·수정 이력·도움 정도·복습 기록을 보관하며, 1/3/7일 복습 간격을 선택할 수 있습니다. 기록 탭을 열 때도 영상이 멈추고(기록 패널의 체크로 끌 수 있음), 내 기록 → 열린 질문은 아직 내 설명도 복습도 없는 질문만 보여 줍니다. 복습 → 예정된 복습에는 앞으로의 회상 날짜가 날짜순으로 있고, 전체 기록 Markdown 내려받기는 모든 기록을 한 파일로 만듭니다. 여러 PC에서 공부하면 백업·동기화 → 여러 PC에서 이어 공부하기에 OneDrive 같은 클라우드 폴더를 정하고, 각 PC에서 내보낸 뒤 다른 PC의 파일을 미리보기로 확인하고 합칩니다. 기록 단위로 합치며 지우는 기록은 없고, 두 PC에서 따로 고친 기록은 나중 수정을 현재 값으로, 다른 쪽을 수정 이력에 둡니다(설계). 진행 상태는 직접 표시하는 활동 기록이며 시청률이나 AI의 긍정 답변이 숙달을 뜻하지 않습니다.

로드맵·기록·복습·백업 화면과 로컬 API가 구현되어 있습니다. 소스에서 확인한 기능과 남은 통합·실사용 검증은 학습·탐구 설계에 구분합니다. 강의·자료 전체 목록은 학습 커리큘럼, 개념별 뜻은 딥러닝 개념 지도, 커리큘럼의 남은 빈틈과 이 앱이 학습자에게 맞는지에 대한 검토는 커리큘럼 재평가에 있습니다. 이미 아는 개념을 체크해 건너뛰며 개념별 강의를 찾으려면 공부 가이드(개념 160개 체크리스트)를 보세요.

실행

현재 전체 기능은 Windows + Node.js 24 이상에서 지원합니다. ChatGPT 인증 정보 보관에는 Windows DPAPI를 사용합니다.

npm ci
npm run setup -- --youtube
npm run prepare:learning
npm run build
npm start

플레이어 열기. 다른 포트가 필요하면 DUVI_PORT 환경 변수로 바꿉니다. 준비가 끝난 뒤에는 Start-Study.vbs를 실행해 서버와 브라우저를 열 수 있습니다.

setup은 MIT 공식 서버에서 26개 강의의 영어 자막을 받아 준비합니다. 기존 자막 파일은 덮어쓰지 않습니다. --youtube 옵션은 Windows용 yt-dlp를 고정된 공식 릴리스에서 내려받고 SHA-256을 확인합니다. 영상 파일은 내려받지 않습니다. MIT 강의만 이용하려면 옵션 없이 npm run setup을 실행하세요.

prepare:learning은 setup 이후 실행합니다. 기존 MIT 강의가 있어야 하며, 로드맵 순서의 폴더와 YouTube 강의 메타데이터를 준비합니다. 다시 실행하면 기존 강의를 재사용하고 폴더 이름 변경과 추가한 강의를 보존합니다. 커리큘럼 강의 순서는 다시 맞춥니다. 이 명령은 영상·YouTube 자막을 다운로드하거나 번역하지 않고 학습 상태도 완료 처리하지 않습니다. YouTube 영어 자막은 각 강의를 열 때 가져옵니다.

npm run prepare:learning -- --help
npm run prepare:learning -- --root "C:\경로\duvi\backend"

다른 데이터 경로를 지정하려면 그 경로에도 먼저 MIT setup 데이터가 준비되어 있어야 합니다.

사용

  • 새 폴더로 강의를 주제별로 묶습니다. 폴더 이름을 눌러 접거나 펼치고, 오른쪽 메뉴에서 이름 변경·폴더 삭제를 할 수 있습니다. 기존 MIT 강의는 ‘MIT Python 기초’ 폴더에 모입니다.

  • 재생목록 추가에 YouTube 재생목록 공유 주소를 붙여넣으면 제목과 원래 영상 순서를 가져옵니다. 기본값은 재생목록 제목의 새 폴더이며, 기존 폴더도 선택할 수 있습니다. 최대 500개까지 지원하고 다시 가져오면 기존 강의를 재사용합니다.

  • 재생목록의 영어 자막은 강의를 처음 열 때 준비합니다. 자막 요청이 제한되면 영어 자막 다시 가져오기 또는 영어 자막 파일 추가로 보완할 수 있습니다. 자막이 없어도 영상을 재생할 수 있으며, 비공개·삭제 영상은 원본 확인 상태로 표시합니다.

  • 강의 오른쪽 이동 버튼으로 폴더를 바꿀 수 있습니다. 폴더 삭제는 강의·자막·번역을 지우지 않습니다. 다른 폴더에 속하지 않은 강의는 ‘미분류’에 표시됩니다.

  • 폴더 이름과 강의 순서는 backend/library/folders.json에 저장됩니다. 다른 PC로 옮길 때 backend/library/와 backend/translations/를 함께 백업하세요.

  • 왼쪽 라이브러리에서 강의를 검색하고 선택합니다.

  • 강의 추가에서 YouTube 영상 주소를 등록합니다. 영어 자막을 가져올 수 없다면 SRT/VTT 파일(2MB 이하)을 보완할 수 있습니다.

  • 설정에서 ChatGPT 계정을 연결하고, 번역 상태에서 모델과 5분/전체 번역 범위를 선택합니다. 계정에서 제공하는 접근 권한과 사용 한도가 적용됩니다.

  • 번역 요청은 영어 자막과 앞뒤 문맥을 OpenAI로 보냅니다. 완료한 번역은 PC에 저장하며 다시 재생할 때 재사용합니다. 중단 후에는 미완료 구간을 이어서 처리합니다.

  • Chrome 기기 내 번역을 선택할 수도 있습니다. 브라우저의 Translator API 지원과 언어 모델 준비가 필요합니다.

  • 입력창과 대화상자 밖에서 ←/→ 문장 이동, R 반복, F 전체화면을 사용합니다.

  • 자막 전체화면은 영상 아래에 영어·한국어를 표시합니다. 각 언어는 최대 두 줄을 온전히 보여 주며 긴 문장은 스크롤할 수 있습니다. 두 언어 사이 간격은 12px입니다.

  • 전체화면의 ⚙에서 자막 위치(영상 아래/영상 위 상단/하단)와 크기를 바꾸고, 대본을 열 수 있습니다. 조작 버튼은 자동으로 숨겨지며 종료 버튼과 Esc를 지원합니다.

다른 컴퓨터에서 사용하기

Windows와 Node.js 24 이상을 준비하고, 새 컴퓨터에서 다음을 실행합니다.

git clone https://github.com/hyperdrivebeep/duvi.git
cd duvi
npm ci
npm run setup -- --youtube
npm run prepare:learning
npm run build
npm start

이미 저장소가 있다면 실행 중인 Duvi 서버를 종료한 뒤 git pull --ff-only, npm ci, npm run build, npm start 순서로 업데이트합니다. 실행 중인 서버는 코드 변경만으로 새 번역 처리 코드를 다시 읽지 않으므로 재시작이 필요합니다.

코드와 개인 학습 데이터는 별도로 옮깁니다. GitHub만 복제하면 추가한 강의 폴더와 저장된 한국어 번역은 따라오지 않습니다. 기존 PC의 다음 폴더를 새 PC 저장소의 같은 경로로 복사하세요. 새로 복제한 저장소에 복원하는 것을 권장합니다.

  • backend/data/: MIT 강의의 영어 원문
  • backend/library/: 추가 강의·영어 자막·폴더와 강의 순서
  • backend/translations/: 문장별 한국어 번역과 맞춰진 영어 문장
  • backend/learning/: 개인 질문·설명·수정/복습 이력·학습 상태와 복원 전 사본

앱에서는 학습 로드맵 → 백업·복원 → 전체 백업 내려받기로 개인 JSON 백업을 만들 수 있습니다. 강의·폴더·번역·학습 기록과 허용된 브라우저 재생 위치·자막 설정을 담습니다. 복원할 파일을 선택해 항목과 충돌 미리보기를 확인한 뒤, 기존 항목 유지 또는 충돌 항목 덮어쓰기를 선택합니다. 저장하지 않은 초안과 인증 정보는 포함되지 않습니다. 백업 JSON과 Markdown 학습 기록은 개인 파일로 보관하고 공개 Git에 올리지 마세요.

backend/ 폴더 구조를 유지한 데이터 ZIP이 있다면 새 저장소에서 Expand-Archive -LiteralPath "C:\경로\duvi-data.zip" -DestinationPath .로 복원합니다. 이미 학습 데이터가 있는 PC에서는 먼저 기존 데이터를 백업하고 같은 이름의 파일을 확인하세요. 영상 파일은 포함되지 않으며 원본 서비스에서 스트리밍합니다.

ChatGPT 연결은 새 PC에서 다시 로그인합니다. 위 폴더를 직접 복사하는 방식에는 브라우저 재생 위치·자막 설정·Chrome 기기 내 번역이 포함되지 않습니다. 앱의 JSON 백업은 허용된 브라우저 키도 담지만 모든 브라우저 설정을 복제하지는 않습니다. 저장된 ChatGPT 번역은 로그인 없이 읽을 수 있습니다. 두 PC 사이에 자동 동기화는 없습니다. 지금 쓸 수 있는 이동 방법과 동기화 설계안은 여러 기기에서 이어 가기에 있습니다.

구조와 저장 위치

브라우저 UI (Vite로 빌드한 일반 JavaScript)
  ├─ MIT HTML video / YouTube IFrame Player
  └─ 같은 주소의 Node.js API
       ├─ 강의·영어 자막 관리
       ├─ ChatGPT 인증 및 문맥 번역
       └─ 강의별 JSON 저장
위치 내용 Git 포함
src/ 화면, 재생·자막 동기화 예
backend/ 로컬 API, 로그인, 번역 코드 예
backend/data/ 설치 시 준비하는 MIT 영어 자막 아니요
backend/library/ 사용자가 추가한 강의·자막 아니요
backend/translations/ 저장한 AI 번역 아니요
backend/learning/ 개인 학습 기록·상태·복원 전 사본 아니요
src/learning-roadmap.mjs 출처 버전을 명시한 공용 학습 로드맵 예
%LOCALAPPDATA%/StudyLibraryPreview/ DPAPI로 암호화한 인증 정보 아니요

서버는 127.0.0.1:6103에만 바인딩합니다. 인증 토큰은 브라우저로 전달하지 않습니다. 학습 데이터·번역·로그·빌드 결과·node_modules는 저장소에서 제외됩니다. 다른 PC에서 저장한 번역을 사용하려면 데이터 폴더를 별도로 백업·복원하세요. 인증 정보는 해당 PC에서 로그인해 준비하세요.

영어·한국어 문장 맞추기

ChatGPT의 전체 강의 번역은 시간 단위로 잘린 원문을 완결된 문장/절로 다시 나누고, 같은 범위의 한국어를 한 쌍으로 저장합니다. 원문 단어의 순서와 누락 여부를 검증하며, 화면·전체 대본·문장 이동·반복 재생에 같은 경계를 사용합니다. 기존 번역은 완료 전까지 유지하고 완료 시 별도 백업합니다. 중단한 작업은 다시 전체 강의 번역을 누르면 이어서 처리합니다. 5분 시험 번역은 기존 구간을 번역하며, 문장 맞추기가 완료된 강의에서는 새 문장 경계를 사용합니다.

원본에 단어별 시간이 없으면 기존 자막 구간 안에서 단어 길이로 시간을 추정하므로 음성과 문장 전환에 약간의 차이가 있을 수 있습니다. 이미 가져온 강의를 서버 재시작 없이 정리하는 관리 명령은 node scripts/align-captions.mjs 강의_ID 모델_ID입니다.

검증

npm test
npm run build

npm test는 먼저 Vite/Sites 빌드를 수행하고 기존 테스트와 backend/tests/learning*.test.mjs, tests/learning-ui*.test.mjs를 실행합니다. 따옴표로 감싼 패턴은 셸 대신 Node.js 24 테스트 러너가 확장합니다. 인증/PKCE, 토큰 검증, 번역 응답·중단·재개, 자막 파싱, HTTP 요청 보호, 재생 위치 복원과 학습 저장·백업·로드맵 관련 테스트를 포함합니다. 실제 브라우저 검증 범위와 미검증 항목은 TEST-RESULTS.md, 학습 기능의 확인 범위는 학습·탐구 설계를 참고하세요. 전체화면·질문하기 QA에서 찍은 화면과 측정값(개인정보를 가린 WebP)은 QA 증거에 있습니다.

선택적 AI 학습 도움

AI 도움은 사용자가 전송할 문맥을 확인하고 직접 요청하는 선택 기능입니다. 저장된 질문·설명 등 학습 필드와 연결한 원문 구간을 기존 ChatGPT 인증 경로로 OpenAI에 전송하도록 구현되어 있습니다. 원문과 현재 자막이 맞는지 확인하며 답변은 AI 제안으로 구분합니다. 관측 결과를 대신 만들거나 숙달을 판정하는 기능이 아닙니다. 계정 연결 없이도 로컬 기록·복습·내보내기를 사용할 수 있습니다. 실제 계정의 AI 응답 성공과 화면 전체 흐름은 자동 테스트만으로 확인되지 않습니다.

자료 출처와 제한

MIT 영상과 영어 자막은 MIT OpenCourseWare가 제공합니다. 해당 자료의 CC BY-NC-SA 4.0 조건이 적용됩니다. 이 저장소에는 강의 자료 자체 대신 공식 출처 목록과 설치 스크립트를 넣습니다.

YouTube 영상·자막의 권리는 각 권리자에게 있습니다. 자막을 가져올 수 없는 영상과 외부 재생이 제한된 영상은 지원하지 못할 수 있습니다. 한국어 자막은 AI 번역이며 정확성을 보증하지 않습니다. 외부 의존성의 출처와 라이선스는 THIRD-PARTY.md를 참고하세요.

전체 기능에는 로컬 Node 서버가 필요합니다. 포함된 Sites 템플릿만 정적으로 배포하면 로그인·가져오기·번역이 동작하지 않습니다.

공개 저장소는 hyperdrivebeep/duvi입니다.

About

Duvi · 두 언어로 배우는 로컬 강의 플레이어 — MIT, YouTube, and contextual Korean subtitles.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages