0%

Frontend

화면 비율이 두 번 바뀐 전시 콘텐츠 — LED 월에 해파리 10마리를 띄우며 배운 것

전*진··수정됨 2026.11.21

화면 비율이 두 번 바뀐 전시 콘텐츠 — LED 월에 해파리 10마리를 띄우며 배운 것

안녕하세요. 전시 콘텐츠를 개발하고 있는 프론트엔드 개발팀입니다!

국립청주해양과학관 해파리 전시에는 관람객이 QR을 찍어 메시지를 보내면, 전시장 큰 화면의 해파리 열 마리 중 한 마리가 그 메시지를 말풍선으로 "말해 주는" 콘텐츠가 있어요. 저희는 이걸 메시지 앱이라고 불러요. Electron으로 만든 Windows 앱이고, 전체화면·관리자 화면 같은 공통 키오스크 동작은 kiosk-core 패키지에서 가져와요.

이 앱은 다른 두 키오스크와 한 가지가 달랐어요. 터치 모니터가 아니라 LED 월에 나간다는 점이었어요. 그리고 그 화면 비율이 개발 중에 두 번 바뀌었어요. 16:9로 만들었다가, 현장에 가 보니 7:5라서 고쳤고, 한 달 뒤에 다시 16:9로 맞춰 달라는 요청을 받았어요.

이 글은 그 두 번의 반전을 겪으면서 화면 크기를 코드 어디에 두어야 하는지, 그리고 해파리 열 마리의 말풍선이 서로 겹치지 않게 하려면 무엇을 실측해야 하는지를 정리한 기록이에요.

목표를 한 문장으로 적으면 이래요.
화면 비율이 바뀌어도 값 하나만 고치면 되고, 말풍선 겹침은 실행 중의 운이 아니라 배포 전의 계산으로 막는다.

1. 메시지가 해파리 입까지 오는 길

구조부터 짧게 볼게요. 모바일 입력 페이지와 백엔드 API는 다른 팀이 만들었고, 저희 앱은 그 API를 읽기만 해요.

관람객 QR → 모바일 페이지 → 백엔드 대기열
                                 ↓ (앱이 주기적으로 GET /api/messages/live)
                        Electron main 프로세스 (폴링·중복 제거·백오프)
                                 ↓ IPC, 1초마다 drain
                        React 렌더러 (누가 무엇을 말할지 정하는 스케줄러)
                                 ↓ 표시가 끝나면 PATCH /displayed 로 ACK

몇 가지 결정을 처음부터 분명히 했어요.

  • 네트워크는 main 프로세스에서만. API 키가 렌더러로 넘어가지 않도록 kiosk-core의 설정 전달 단계에서 키를 지우는 훅을 두었어요. 브라우저에서 단독으로 띄우는 개발 모드만 예외예요.

  • 같은 메시지를 두 번 말하지 않기. 서버가 한 번 준 메시지를 다시 주든 안 주든 결과가 같도록, 최근 id 2,000개를 기억해 걸러요. 표시가 끝나면 ACK를 보내 서버 대기열에서도 빼요.

  • 서버가 죽어도 화면은 살아 있기. 폴링 실패는 지수 백오프(최대 60초)로 물러나고, 관리자 화면에 마지막 성공 시각과 실패 사유를 띄워요. 전시 체험이 네트워크 때문에 멈추면 안 되니까요.

  • 목 서버를 저장소 안에. /live와 /displayed를 흉내 내는 작은 Node 서버를 두고, 개발·E2E·가이드 캡처가 전부 이걸 써요. 외부 팀 서버가 준비되기 전부터 화면을 만들 수 있었어요.

첫 버전은 하루 만에 올라갔어요. 그런데 진짜 어려운 문제는 네트워크가 아니라 화면 위에 있었어요.

2. 말풍선 겹침은 운에 맡기지 않기로 했어요

해파리는 열 마리고, 메시지는 최대 20자예요. 말풍선 하나는 폭 320px에 두세 줄이 들어가요. 1920 폭 화면에 열 마리를 흩뿌리면 누가 말하느냐에 따라 말풍선이 이웃 해파리 몸을 가리는 일이 생겨요.

처음에는 "말하는 해파리를 맨 앞으로 올리면 되지 않나" 싶었어요. 실제로 말하는 해파리의 z-index를 올려 두긴 했어요. 하지만 그건 가려지는 쪽을 바꿀 뿐, 겹침 자체를 없애지는 못해요. 전시장에서는 어떤 메시지가 어느 해파리에게 갈지 아무도 모르니까, 겹침은 배포 전에 기하로 막아야 했어요.

말풍선 위치는 실측하지 않고 계산해요

말풍선은 머리 위 중앙에 붙고, 화면 밖으로 나가면 안쪽으로 밀어요. 이 "미는 양"을 DOM 실측으로 구하면 안 됐어요. 등장 애니메이션이 scale(0)에서 시작해서 첫 렌더의 getBoundingClientRect()가 0으로 나오거든요. 그래서 슬롯 좌표만으로 산술 계산해요.

// bubbleLayout.ts — 무대 폭 1920이 고정이라 실측 없이 결정적으로 계산한다
export function bubbleOffset({ anchorX, anchorTop, width, height }: BubbleAnchor) {
  const left = anchorX - width / 2;
  const right = anchorX + width / 2;
  const shiftX = Math.max(EDGE - left, Math.min(0, STAGE_WIDTH - EDGE - right));
  const top = anchorTop - BUBBLE_GAP - (height + BUBBLE_TAIL);
  const shiftY = Math.max(0, EDGE - top);
  return { shiftX, shiftY };
}

입력이 같으면 출력이 같으니, 테스트도 "이 좌표면 이만큼 밀린다"로 적을 수 있어요.

그래도 남는 조합은 스케줄러가 피해요

좌표를 아무리 잘 잡아도, 두 마리가 동시에 말할 때 말풍선끼리 겹치는 쌍은 남을 수 있어요. 이건 좌표를 더 벌리는 대신 슬롯마다 conflicts 목록을 두고, 스케줄러가 그 쌍을 동시에 배정하지 않게 했어요. 이 목록은 대칭이어야 해서 테스트가 검증해요.

스케줄러 자체는 시간과 난수를 주입받는 순수 함수예요. "지금 말하지 않는 해파리 중 하나에게 랜덤 배정, 전부 말하는 중이면 최소 표시 시간을 채운 순서대로 교체, 말풍선 수명은 화면 점유율에 따라 15초에서 240초 사이"라는 규칙을 가짜 시계로 초 단위까지 검증할 수 있었어요. 관람객이 없을 때는 45초 뒤부터 해파리 세 마리가 번갈아 안내 문구를 말해요.

이렇게 해 두고 나니, 화면 비율이 바뀌었을 때 "무엇을 다시 계산해야 하는지"가 분명했어요. 그 일이 곧 닥쳤어요.

3. 첫 번째 반전 — 현장은 7:5 LED 월이었어요

스펙 문서에는 장비가 "기존과 같은 1920×1080 가로 키오스크"라고 적혀 있었어요. 그 기준으로 만들어 1.0.2까지 배포했는데, 현장 사진을 보니 해파리가 세로로 길쭉했어요.

알고 보니 화면은 3500×2500, 그러니까 7:5 비율의 LED 월이었어요. 디자이너가 준 배경 영상 원본도 3500×2500이었는데, 저희가 그걸 16:9로 크롭해 쓰고 있었던 거예요. 16:9 화면을 7:5 월 전체로 늘리니 모든 게 27% 길어 보였어요.

02-stage-7x5.png

무대 크기를 한 곳에 모았어요

고치려고 코드를 열어 보니 1080이라는 숫자가 세 군데에 흩어져 있었어요. 해파리 컴포넌트, 앱 루트, CSS. 이걸 전부 없애고 훅 하나를 단일 출처로 삼았어요.

// useStageScale.ts — 무대 크기는 여기서만 정한다
export const STAGE_WIDTH = 1920;
export const STAGE_HEIGHT = 1371; // 1920 × 2500/3500

export function useStageScale(): void {
  useEffect(() => {
    const root = document.documentElement.style;
    root.setProperty('--stage-width', `${STAGE_WIDTH}px`);
    root.setProperty('--stage-height', `${STAGE_HEIGHT}px`);
    const apply = () => {
      const scale = Math.min(1, window.innerWidth / STAGE_WIDTH, window.innerHeight / STAGE_HEIGHT);
      root.setProperty('--stage-scale', scale.toFixed(4));
    };
    apply();
    window.addEventListener('resize', apply);
    return () => window.removeEventListener('resize', apply);
  }, []);
}

무대는 절대 좌표 1920×(높이)짜리 박스 하나고, CSS 변수로 크기를 받아 transform: scale()로 창에 맞춰 줄어들어요. 폭 1920은 바꾸지 않았어요. kiosk-core가 창 폭이 몇이든 CSS 뷰포트 폭을 1920으로 줌하기 때문에, 폭을 고정해 두면 x 좌표·글자 크기·말풍선 폭이 전부 그대로예요. 높이만 바꾸면 되는 구조로 만든 거예요.

해파리 y 좌표는 1371/1080배로 일괄 이동했어요. 세로 간격만 일제히 1.27배 벌어지니, 1080에서 겹치지 않던 관계가 그대로 성립해요. 배경 영상은 원본을 크롭 없이 1920×1372로 다시 변환했고, E2E와 가이드 캡처 뷰포트도 7:5로 바꿨어요.

LED 월에서 알게 된 것들

  • 터치가 안 돼요. 관리자 화면은 모서리를 다섯 번 터치해서 여는데, LED 월에는 터치가 없어요. PC에 마우스를 꽂아 같은 자리를 클릭하면 열리도록 하고, 가이드에 그렇게 적었어요.

  • Windows 출력 해상도를 앱이 알 수 없어요. 앱은 받은 창을 채울 뿐이라, PC가 16:9로 내보내고 LED 컨트롤러가 늘리면 앱을 고쳐도 소용없어요. 관리자 화면에 현재 해상도를 "화면 구성" 줄로 띄워서, 현장에서 사진 한 장으로 확인할 수 있게 했어요.

  • 줌 방식을 고를 수 있게 했어요. LED 송출 카드처럼 물리 픽셀 영역을 잘라 가는 장비를 위해 kiosk-core에 CSS 1px = 물리 1px로 고정하는 pixel 모드를 추가했어요. 기본은 여전히 뷰포트 폭을 1920으로 맞추는 design 모드예요.

여기까지가 9월이었어요. 10월에 QR과 최근 메시지 띠를 화면 아래에서 위로 옮기고, QR 코드를 더 키우는 작은 변경이 두 번 있었어요. 이 두 변경이 다음 반전에서 발목을 잡을 줄은 몰랐어요.

4. 두 번째 반전 — "1920×1080으로 맞춰 주세요"

10월 말, 현장에서 출력 해상도를 1920×1080으로 쓰기로 했다는 연락이 왔어요. 무대를 다시 16:9로 돌려야 했어요.

값 하나만 바꾸면 되는 구조를 만들어 뒀으니 STAGE_HEIGHT를 1080으로 돌리는 건 한 줄이었어요. 문제는 해파리 배치였어요. 1.0.2 때 쓰던 1080 좌표를 그대로 되살릴 수 없었거든요. 그때는 QR과 띠가 화면 아래에 있었는데, 지금은 위에 있어요. 위쪽 80px(띠)과 오른쪽 위 150px(QR 패널)을 말풍선이 피해야 하는데, 세로는 291px이 줄었어요.

먼저 실측했어요

감으로 좌표를 옮기면 반드시 어딘가 겹쳐요. 그래서 Playwright로 실제 앱을 띄우고, 실제 폰트로 말풍선 글 상자 크기를 쟀어요. 안내 문구 12개, 터치 반응 4개, 그리고 20자 안에서 가장 불리하게 줄바꿈되는 문장들을 넣어 봤어요.

본문

글자 수

글 상자

가나다라마바사아자차카타파하가나다라마바

20

320×114 (2줄)

바다에서 만난 해파리들 정말로 예뻐요

20

320×153 (3줄)

누구 없어?

6

179×75 (1줄)

같은 20자라도 띄어쓰기 위치에 따라 2줄이 되기도, 3줄이 되기도 해요. word-break: keep-all 때문에 단어 단위로 꺾이거든요. 해파리 이미지 열 장의 표시 크기와 QR 패널·띠의 위치도 같은 방법으로 읽었어요.

그다음 탐색했어요

x 좌표와 해파리 크기는 그대로 두고, y 열 개만 변수로 잡았어요. 조건은 이렇게 나눴어요.

  • 반드시: 2줄 말풍선(위아래 유영 ±14px 포함)은 어떤 해파리 몸과도 겹치지 않는다. 3줄 말풍선은 띠·QR 패널·좌상단 관리자 탭 영역·화면 가장자리와 겹치지 않는다. 몸은 아래 가장자리 16px 안에 든다.

  • 가능하면: 3줄 말풍선도 이웃 몸과 겹치지 않는다. 원래 좌표에서 많이 벗어나지 않는다.

  • 남으면 기록: 3줄 말풍선끼리 겹치는 쌍은 conflicts에 넣는다.

이걸 점수로 만들어 담금질 비슷한 무작위 탐색을 돌렸어요. 스크립트는 100줄 남짓이고, 몇 초면 끝나요.

결과는 솔직하게 적어야 해요. "반드시" 조건은 전부 만족했지만 "가능하면" 조건은 다 못 지켰어요. 20자 본문이 3줄로 꺾이면 이웃 해파리의 촉수 끝과 최대 40px쯤 닿을 수 있어요. 1080 무대에서 열 마리와 상단 UI를 함께 넣으면 세로 예산이 그만큼밖에 없었어요. 1.0.2의 1080 배치도 같은 수준이었다는 걸 확인하고, 이 정도는 받아들이기로 했어요. 촉수 끝은 반투명이라 눈에 거의 띄지 않거든요. 3줄 말풍선끼리 겹칠 수 있는 세 쌍은 conflicts로 넣어 동시에 말하지 않게 했어요.

마지막으로 눈으로 확인했어요

탐색 결과를 코드에 넣고, 가장 불리한 3줄 문장을 열 마리 전부에게 지정해서 띄워 봤어요. 목 서버에 jellyfish 필드로 슬롯을 지정할 수 있게 해 둔 덕이에요. DOM에서 실제 간격을 다시 재고, 캡처를 보면서 QR·띠와 겹치지 않는지 확인했어요.

02-stage-7x5.png02-stage-7x5.png

단위 테스트 123개와 E2E 5개를 돌리고, 발주처 가이드의 캡처 4장을 다시 찍고, 화면 규격과 해상도 안내 문구를 고쳐서 MR을 올렸어요. 머지 뒤 태그를 push하니 몇 분 뒤에 현장 키오스크가 받을 수 있는 상태가 됐어요.

04-messages-1080.png

5. 덤으로 고친 것 — 같은 커밋에 CI가 두 번 돌고 있었어요

릴리스를 하다가 파이프라인 목록에 같은 커밋이 두 줄 떠 있는 걸 봤어요. 브랜치 파이프라인 하나, MR 파이프라인 하나.

.gitlab-ci.yml에는 "열린 MR이 있는 브랜치는 브랜치 파이프라인을 건너뛴다"는 규칙이 있었어요. 그런데 저희는 git push -o merge_request.create로 push와 MR 생성을 한 번에 해요. 이러면 브랜치 파이프라인이 MR보다 먼저 만들어져서, 그 시점엔 열린 MR이 없다고 판단하고 둘 다 돌아요. Runner가 맥북 한 대라 릴리스 대기가 매번 4분씩 길어지고 있었어요.

# 파이프라인은 세 종류만 만든다: MR, main 브랜치, 태그
workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
    - if: '$CI_COMMIT_TAG'

작업 브랜치는 MR 파이프라인만 돌도록 바꿨어요. MR 없이 push만 한 브랜치는 CI가 돌지 않지만, main이 보호 브랜치라 모든 변경이 MR로 들어오는 저희 흐름에서는 잃는 게 없었어요.

6. 돌아보면

화면 규격은 코드가 아니라 현장이 정해요. 스펙에 적힌 해상도를 믿고 세 군데에 숫자를 박아 뒀다면 두 번의 반전마다 세 군데를 뒤졌을 거예요. 단일 출처 하나와 CSS 변수로 만들어 두니 두 번째 반전은 한 줄이었어요. 대신 "무엇이 그 값에 의존하는지"는 주석으로 남겨 두어야 해요. 해파리 y 좌표, 배경 영상, E2E 뷰포트, 가이드 캡처가 전부 따라 바뀌어야 했거든요.

겹침은 실측하고 계산해요. 말풍선 크기는 폰트와 줄바꿈 규칙에 달려 있어서 머릿속으로는 못 맞춰요. 실제 브라우저에서 재고, 조건을 적고, 탐색하고, 다시 재는 순서가 결국 가장 빨랐어요. 그리고 다 못 지킨 조건은 숨기지 않고 주석과 커밋 메시지에 적어 두었어요. 다음 사람이 "왜 이 좌표지?"를 묻지 않도록요.

한 번 고친 가정도 다시 바뀔 수 있어요. 7:5로 고칠 때 "이제 됐다"고 생각했지만 한 달 뒤에 돌아갔어요. 되돌리기 쉬운 구조를 만든 게 결과적으로 가장 큰 보험이었어요.

읽기 도구

약 15분 읽기

이 글이 도움이 되었나요?

Work with GIWorks

프로젝트에 GIWorks의 경험이 필요하신가요?

전시·콘텐츠·엔지니어링 프로젝트의 아이디어와 고민을 들려주세요. 필요한 기술과 실행 방법을 함께 찾겠습니다.

문의하기

다음으로 읽기