이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
GitHub README에 유튜브 영상을 넣는 방법을 시도하다가 몇 번 헛걸음했다. 이를 정리해보고자 한다.
iframe은 왜 안 되나?
유튜브가 주는 임베드 코드를 그대로 붙이면 아무것도 안 나온다.
<iframe src="https://www.youtube.com/embed/9UTrqN8X3jg"></iframe>
GitHub은 README를 렌더할 때 HTML을 살균(sanitize)한다. 즉, iframe, script,
style 같은 태그는 제거된다. 남의 저장소를 열었을 때 iframe으로 임의의 페이지가 실행되면
막기 위한 조치일 것이다. 결론은 GitHub README 안에서 유튜브 영상을 재생시키는 방법은 없다.
mp4를 저장소에 커밋해 놓고 video 태그로 부르는 것도 안 된다. 이 태그도 같이 잘린다.
GitHub이 재생기로 바꿔 주는 건 이슈나 PR 댓글창에 파일을 끌어다 놓았을 때 생기는
github.com/user-attachments/assets/... 주소뿐이다. 태그가 막힌 것이 아니고 주소의
출처를 보고 막는 것 같다. 그리고 어차피 영상이 이미 유튜브에 있다면 쓸 일이 없다.
결국 가능한 방법은 하나뿐이다. 영상처럼 보이는 그림에 유튜브 링크를 거는 것이다.
그냥 링크로 두면 안 되나?
[데모 영상](https://youtu.be/9UTrqN8X3jg)
된다. 그런데 아무도 안 누른다. README를 훑는 사람 눈에는 그냥 파란 글씨 한 줄이고 그게 영상인지 문서인지 알 수 없다. 읽는 사람은 스크롤 하다가 무심코 지나가기 일쑤다.
썸네일을 넣으면?
유튜브는 영상마다 썸네일을 정해진 주소로 준다. 영상 ID가 9UTrqN8X3jg라면:
https://i.ytimg.com/vi/9UTrqN8X3jg/maxresdefault.jpg
maxresdefault가 없는 영상도 많다. 그럴 땐 sddefault → hqdefault → mqdefault
순으로 내려가면 대개 하나는 있다. 이걸 이미지로 넣고 링크를 걸면 이렇게 된다.
[](https://youtu.be/9UTrqN8X3jg)
한 발 나아갔는데 아직 부족하다. 그냥 사진 한 장으로 보인다. 유튜브 영상 링크인지 인지하기가 어렵다. 그래서 유튜브 재생 버튼을 링크 이미지 위에 합성을 하여 이를 인지하기 쉽게 하는 방법이 떠올랐다.
그래서 만든 것
재생 버튼을 합성해 주는 도구를 만들었다.
yt-play-thumb는 유튜브 주소를 넣으면 재생 버튼이 얹힌 썸네일과 README에 그대로 붙일 마크다운을 같이 만들어 준다.
이 툴의 특징은 다음과 같다.
결과물이 내 저장소의 파일이다. 비슷한 서비스들이 있는데(Markdown-Videos, video-to-markdown) 전부 남의 서버가 이미지를 실시간으로 만들어 준다. 편하지만 그 서버가 멈추면 내 README의 이미지가 깨진다. 이 도구는 JPG를 내려받아 저장소에 넣는 방식이라 그런 의존이 없다.
서버로 아무것도 보내지 않는다. 썸네일을 가져오고 버튼을 그리고 JPG로 내보내는 걸 전부 브라우저 안에서 한다. 백엔드가 없다.
내 이미지도 쓸 수 있다. 유튜브 썸네일이 마음에 안 들면 직접 만든 그림을 올려서 재생 버튼만 얹을 수 있다.
한계점
받은 JPG를 README와 같은 폴더에 둬야 한다. 마크다운만 복사해 붙이면 이미지가 깨진다. 스니펫 옆에 그 안내를 주석으로 같이 넣어 두긴 했다.
Shorts는 안 된다. 세로 영상이라 재생 버튼 비율과 크롭 규칙이 다르다. 지원 형식은
youtu.be/ID, youtube.com/watch?v=ID, /embed/ID, /live/ID, 그리고 11자 ID
그대로다.
썸네일에 검은 띠가 있으면 잘라 낸다. 4:3 프레임에 16:9 영상이 들어가면 위아래에 띠가 생기는데, 그대로 두면 버튼이 영상 화면 밖에 놓인다. 자동으로 감지해서 자르고 자른 만큼을 화면에 알려 준다.