annotator.js 활용법 (설치, 모듈설정, 스크립트분석)
공부를 잘 하는 사람들은 정리를 잘 할까요, 아니면 정리 도구를 잘 만들까요? 저는 유재석 씨의 유튜브 채널 “뜬뜬”을 보면서 대화 능력을 키우려다, 결국 A4 용지와 형광펜 대신 웹 애노테이션 도구를 직접 만드는 길로 빠졌습니다. annotator.js라는 자바스크립트 라이브러리를 활용해 유튜브 스크립트에 밑줄을 긋고, 메모와 태그까지 붙이는 앱을 만들었던 그 과정을 이번 글에서 풀어보겠습니다.
형광펜을 버리게 된 이유
프로그래머로 오래 살다 보면 역설적인 순간이 찾아옵니다. 코드는 곧잘 짜는데, 사람 앞에서 말 한마디 제대로 못 꺼내는 자신을 발견하는 순간입니다. 저도 그랬습니다. 대화가 어색하다는 걸 느끼고 나서, 토크의 달인이라 불리는 유재석 씨가 어떤 방식으로 질문하고 어떤 타이밍에 웃음을 만드는지 분석해보기로 했습니다.
처음엔 단순했습니다. 뜬뜬 새 에피소드가 올라오면 자막을 A4에 출력하고, 노란 형광펜으로 질문 패턴에 줄을 긋고, 초록색으로 답변 포인트를 표시했습니다. 그런데 어느 날 책상에 쌓인 출력 용지를 보면서 이건 아니다 싶었습니다. 낭비도 문제였지만, 더 솔직히 말하면 주변에 “대화 공부를 하고 있다”는 게 알려지는 게 달갑지 않았습니다. 프로그래머가 말하는 법을 공부한다는 게 왠지 부끄러웠거든요. 그래서 생각했습니다. 이걸 디지털로 해결하면 되지 않을까.
웹 애노테이션(Web Annotation)이란 웹 페이지나 HTML 문서 위에 사용자가 직접 하이라이트, 메모, 태그 등을 추가할 수 있는 기술을 말합니다. 종이 위에 형광펜 긋듯, 브라우저 위에서 동일한 작업을 디지털로 수행하는 방식입니다. 이 개념을 구현한 라이브러리가 바로 annotator.js였고, 제가 찾던 해답이었습니다.
annotator.js 설치와 기본 구조 이해하기
annotator.js를 처음 접했을 때 솔직히 이게 가능할까 하는 생각이 들었습니다. 라이브러리 하나로 하이라이트, 메모, 태그까지 한 번에 해결된다는 게 믿기지 않았거든요. 그런데 실제로 써보니 예상 밖이었습니다. 구조 자체가 상당히 직관적이었습니다.
annotator.js는 설치 후 페이지에 단 하나의 객체, annotator를 노출시킵니다. 이 객체를 통해 핵심 진입점인 annotator.App에 접근하는 방식입니다. annotator.App이란 전체 애노테이션 기능을 조율하는 중앙 제어 객체로, 쉽게 말해 모든 기능이 이 앱 인스턴스를 중심으로 돌아간다고 보면 됩니다. 가장 기본적인 실행 코드는 이렇습니다.
var app = new annotator.App(); 그리고 app.start();를 호출하면 끝입니다. 단 두 줄. 하지만 이 상태만으로는 눈에 보이는 기능이 거의 없습니다. 실질적인 기능은 모두 모듈(Module)을 통해 붙이는 구조이기 때문입니다. 모듈이란 특정 기능 단위로 쪼개진 독립적인 컴포넌트를 말하며, 필요한 것만 골라서 앱에 추가할 수 있습니다. 이 방식 덕분에 불필요한 기능을 억지로 끌어안지 않아도 됩니다.
실제로 유용하게 쓰려면 최소 두 가지를 붙여야 합니다. 기본 UI를 담당하는 annotator.ui.main 모듈과, 애노테이션 데이터를 저장하는 annotator.storage.http 모듈입니다. 이 두 모듈을 app.include()로 추가하고 나서야 하이라이트를 그으면 데이터가 서버에 저장되는 구조가 완성됩니다. 제가 직접 붙여보면서 모듈 구조의 장점을 실감한 부분이기도 합니다.
모듈 설정으로 내 입맛에 맞게 꾸미기
기본 구조를 잡고 나면 이제 진짜 재미가 시작됩니다. annotator.js의 모듈들은 각각 옵션을 받아서 동작 방식을 바꿀 수 있습니다. 예를 들어 annotator.storage.http 모듈은 prefix라는 옵션으로 API 엔드포인트(API Endpoint), 즉 서버와 통신하는 주소를 지정할 수 있습니다. 만약 annotator-store 서버가 http://example.com/api에 올라가 있다면, app.include(annotator.storage.http, { prefix: ‘http://example.com/api’ }) 형태로 넘겨주면 됩니다.
제 경우에는 유튜브 스크립트를 로컬 HTML로 띄운 후 여기에 annotator.js를 붙였습니다. 스크립트 원문은 yt-dlp라는 오픈소스 라이브러리를 활용해 가져왔습니다. yt-dlp란 YouTube를 포함한 다양한 영상 플랫폼에서 자막과 영상 데이터를 추출할 수 있는 커맨드라인 도구로, 개발자들 사이에서 yt-dlp가 사실상 표준으로 자리 잡았다는 평가가 많습니다(출처: yt-dlp GitHub).
스크립트를 HTML로 불러온 뒤, 색상 기준을 직접 정해서 하이라이트를 구분했습니다. 질문 패턴에는 노란색, 답변 포인트에는 초록색, 이런 식으로요. 이렇게 색깔별로 분류를 해두니 나중에 “유재석 씨가 어떻게 질문을 여는지”만 빠르게 복습하고 싶을 때 노란 하이라이트만 훑으면 됐습니다. 생각보다 훨씬 효율적이었습니다.
그리고 한 가지를 더 붙였습니다. 스크립트의 특정 줄을 클릭하면 유튜브의 해당 타임스탬프(Timestamp), 즉 특정 재생 시점으로 바로 이동하는 기능입니다. 이 기능 덕분에 밑줄 친 부분을 읽다가 바로 영상으로 넘어가 실제 말투와 뉘앙스까지 확인할 수 있었습니다. 텍스트와 영상을 동시에 분석하는 방식이 된 셈입니다.
annotator.js가 제공하는 주요 기능을 정리하면 다음과 같습니다.
- 하이라이트(Highlight): 텍스트 선택 후 색상 지정으로 강조 표시
- 메모(Annotation): 선택한 텍스트에 자유 메모를 첨부하는 기능
- 태그(Tag): 메모에 키워드 태그를 달아 나중에 분류·검색 가능
- 스토리지 연동(Storage Integration): http 모듈을 통해 서버에 저장하거나 로컬에 유지
- 타임스탬프 연동: 텍스트와 외부 미디어 재생 시점을 연결하는 커스텀 확장
스크립트 분석 앱을 실제로 써보면서 느낀 것
앱이 완성됐을 때 솔직히 좀 뿌듯했습니다. 기능적으로는 꽤 잘 돌아갔고, 무엇보다 아무도 제가 대화 공부를 하는지 모른다는 점에서 심리적 해방감이 있었습니다. 그런데 막상 써보면서 예상치 못한 부분에서 더 많은 것을 배웠습니다.
직접 질문 패턴에 노란 하이라이트를 치면서 보니, 좋은 질문에는 공통점이 있었습니다. 상대방이 대답하기 쉬운 출발점을 먼저 만들어줬습니다. 막연히 “어떻게 생각해요?”가 아니라, 상대의 경험에서 구체적인 한 지점을 짚어주는 방식이었습니다. 이건 글로 읽는 것과 직접 태그를 붙여가며 분류하는 것의 차이가 꽤 크다는 걸 느낀 순간이었습니다.
기술적으로는 난관도 많았습니다. 특히 프로미스(Promise) 처리가 초반에 좀 헷갈렸습니다. 프로미스란 비동기 작업의 완료 또는 실패를 나타내는 자바스크립트 객체로, annotator.js에서 app.start()가 반환하는 것이 바로 이 프로미스입니다. app.start().then() 체인으로 앱이 완전히 뜬 후에 애노테이션 데이터를 불러오는 순서를 맞춰야 했는데, 이 부분에서 처음에 타이밍 오류가 좀 났습니다. 공식 문서(출처: annotatorjs.com)를 여러 번 다시 읽고 나서야 정리가 됐습니다.
모바일 대응도 신경 쓴 부분입니다. 통근길에 가볍게 복습하고 싶었기 때문에 터치로도 하이라이트가 잘 잡히는지 테스트를 여러 번 거쳤습니다. annotator.js 자체가 모바일 환경에서의 텍스트 선택을 지원하는 구조여서 생각보다 수월하게 해결됐습니다. 제 경험상 이 라이브러리가 없었다면 같은 기능을 처음부터 짜는 데 몇 배는 더 걸렸을 것 같습니다.
자주 묻는 질문
Q. annotator.js를 사용하려면 서버가 반드시 필요한가요?
A. 반드시 필요하지는 않습니다. annotator.storage.http 모듈을 붙이면 원격 서버에 저장할 수 있지만, 로컬 스토리지 방식으로 구현하거나 저장 기능 없이 UI만 붙여서 사용하는 것도 가능합니다. 어떤 저장 방식이 본인 상황에 맞는지 먼저 따져보는 게 좋습니다.
Q. yt-dlp로 유튜브 자막을 가져올 때 한국어 자막도 잘 추출되나요?
A. 네, 한국어 자막도 잘 추출됩니다. yt-dlp에서 –write-sub –sub-lang ko 옵션을 지정하면 한국어 자막 파일을 받을 수 있고, 자동 생성 자막과 수동 자막 모두 지원합니다. 다만 자동 생성 자막은 오탈자나 어순이 어색한 경우가 있어서 직접 훑어보면서 정리하는 과정이 한 번 더 필요하다는 점은 감안해야 합니다.
Q. annotator.js에서 태그(Tag) 기능은 별도 설정이 필요한가요?
A. 기본 설치만으로는 태그 기능이 바로 켜지지 않습니다. annotator.ui.main 모듈 안에 태그 관련 컴포넌트가 포함돼 있지만, 공식 문서의 예제 코드를 참고해 별도로 활성화 설정을 해줘야 합니다. 저도 처음에 태그가 안 보여서 한참 헤맸는데, 문서에 태그 기능을 구현해 놓은 예제가 따로 있어서 그걸 참고하니 해결됐습니다.
Q. 텍스트를 클릭하면 유튜브 특정 시점으로 이동하는 기능은 어떻게 구현하나요?
A. annotator.js 자체 기능은 아니고, 스크립트 각 줄에 타임스탬프 데이터를 data 속성으로 심어두고, 클릭 이벤트 발생 시 유튜브 URL의 t 파라미터에 해당 시간 값을 넘기는 방식으로 구현했습니다. yt-dlp로 자막을 추출할 때 타임스탬프 정보도 함께 뽑을 수 있어서 연결하는 데 어렵지 않았습니다.
annotator.js로 뭔가를 만들어보려 한다면, 처음부터 완성된 그림을 그리기보다 app.start() 두 줄부터 돌려보는 것이 훨씬 빠른 길입니다. 제가 그랬듯 모듈을 하나씩 붙여가다 보면 어느새 본인만의 분석 환경이 만들어져 있을 겁니다. 대화 공부를 위해 만든 도구가 결국 개발 공부에도 도움이 됐다는 게 좀 웃기기도 하지만, 그게 직접 만들어 쓰는 것의 묘미 아닐까 싶습니다.
—
참고: https://annotatorjs.com/docs/usage
https://github.com/yt-dlp/yt-dlp