shj.rip

clarify codex skill

shj — Sat, 04 Apr 2026 00:00:00 GMT

## 시작애매한 요청으로 구현하게 되면 planning 단계와 AskUserQuestion을 거친다 해도 디테일을 놓칠 때가 종종 있다. 이를 보완하고자 cc에서는 https://github.com/team-attention/plugins-for-claude-natives?tab=readme-ov-file#clarify `clarify` plugin 을 사용했다. 이름 그대로 모호한 요구사항을 질문으로 쪼개서 실제로 작업 가능한 형태로 바꾸는 역할이다. 이게 codex 용으로는 없었다. 그래서 codex 에게 분석 및 포팅해달라고 했다.특히 openclaw 사용할 때 유용하다. 일반적으로 아래와 같은 흐름으로 진행되는데:- 원문 요구사항을 먼저 그대로 적는다- ambiguity 를 찾는다- 한 번에 하나씩, 선택지 중심으로 질문한다 (예: 선택지 주고 내가 거기에 1, 2, 3 번호로 답하기)- 마지막엔 Before/After 로 정리한다- 원하면 파일로 저장한다질문 방식도 규칙이 있다.- specific over general- options over open-ended- one concern at a time- neutral framing아무튼 planning 단계에서 빠진 결정들이나 디테일을 모두 챙겨준다. skill 원문에도 보면 `No assumptions`, `Preserve intent`, `Minimal questions` 같은 규칙이 들어가 있음을 볼 수 있다.## Codex Skill현재 local codex global `clarify` skill 은 아래와 같다.

clarify

````md---name: clarifydescription: This skill should be used when the user asks to "clarify requirements", "refine requirements", "specify requirements", "what do I mean", "make this clearer", or when the user's request is ambiguous and needs iterative questioning to become actionable. Also trigger when user says "clarify", "/clarify", or mentions unclear/vague requirements.---# ClarifyTransform vague or ambiguous requirements into precise, actionable specifications through iterative questioning.## PurposeWhen requirements are unclear, incomplete, or open to multiple interpretations, use structured questioning to extract the user's true intent before any implementation begins.## Protocol### Phase 1: Capture Original RequirementRecord the original requirement exactly as stated:```markdown## Original Requirement"{user's original request verbatim}"```Identify ambiguities:- What is unclear or underspecified?- What assumptions would need to be made?- What decisions are left to interpretation?### Phase 2: Iterative ClarificationAsk the user iteratively to resolve each ambiguity. Continue until ALL aspects are clear.**Question Design Principles:**- **Specific over general**: Ask about concrete details, not abstract preferences- **Options over open-ended**: Provide 2-4 choices (recognition > recall)- **One concern at a time**: Avoid bundling multiple questions- **Neutral framing**: Present options without bias**Loop Structure:**```while ambiguities_remain: identify_most_critical_ambiguity() ask_the_user_a_clarifying_question() update_requirement_understanding() check_for_new_ambiguities()```**Question Format:**Ask the user with a clear question and provide labeled options with descriptions. For example:> **Question**: What authentication method should be used?>> Options:>> 1. **Username/Password** - Traditional email/password login> 2. **OAuth** - Google, GitHub, etc. social login> 3. **Magic Link** - Passwordless email link### Phase 3: Before/After ComparisonAfter clarification is complete, present the transformation:```markdown## Requirement Clarification Summary### Before (Original)"{original request verbatim}"### After (Clarified)**Goal**: [precise description of what user wants]**Scope**: [what's included and excluded]**Constraints**: [limitations, requirements, preferences]**Success Criteria**: [how to know when done]**Decisions Made**:| Question | Decision ||----------|----------|| [ambiguity 1] | [chosen option] || [ambiguity 2] | [chosen option] |```### Phase 4: Save OptionAsk the user if they want to save the clarified requirement:> **Question**: Save this requirement specification to a file?>> Options:>> 1. **Yes, save to file** - Save to requirements/ directory> 2. **No, proceed** - Continue without savingIf saving:- Default location: `requirements/` or project-appropriate directory- Filename: descriptive, based on requirement topic (e.g., `auth-feature-requirements.md`)- Format: Markdown with Before/After structure## Ambiguity CategoriesCommon types to probe:| Category | Example Questions || --------------- | --------------------------------------- || **Scope** | What's included? What's explicitly out? || **Behavior** | Edge cases? Error scenarios? || **Interface** | Who/what interacts? How? || **Data** | Inputs? Outputs? Format? || **Constraints** | Performance? Compatibility? || **Priority** | Must-have vs nice-to-have? |## Examples### Example 1: Vague Feature Request**Original**: "Add a login feature"**Clarifying questions (ask the user iteratively)**:1. Authentication method? -> Username/Password2. Registration included? -> Yes, self-signup3. Session duration? -> 24 hours4. Password requirements? -> Min 8 chars, mixed case**Clarified**:- Goal: Add username/password login with self-registration- Scope: Login, logout, registration, password reset- Constraints: 24h session, bcrypt, rate limit 5 attempts- Success: User can register, login, logout, reset password### Example 2: Bug Report**Original**: "The export is broken"**Clarifying questions**:1. Which export? -> CSV2. What happens? -> Empty file3. When did it start? -> After v2.1 update4. Steps to reproduce? -> Export any report**Clarified**:- Goal: Fix CSV export producing empty files- Scope: CSV only, other formats work- Constraint: Regression from v2.1- Success: CSV contains correct data matching UI## Rules1. **No assumptions**: Ask, don't assume2. **Preserve intent**: Refine, don't redirect3. **Minimal questions**: Only what's needed4. **Respect answers**: Accept user decisions5. **Track changes**: Always show before/after````

OpenClaw 살아있게 만들기

shj — Sat, 28 Mar 2026 00:00:00 GMT

밖에서 PC 접속이 어렵기에 나는 OpenClaw가 영원히 살아있기를 원한다. 그리고 몇 가지 시행착오를 겪었다. 여기에 계속 업데이트 할 예쩡.### KeepAliveOpenClaw가 스스로 죽이는 멍청한 행동을 할 때가 있다. 그래서 죽어도 계속 살아있도록 launchd KeepAlive 이용해 OpenClaw 를 실행했다.### Auto Restart (Gateway, Telegram)그런데 또 어느날 동작을 안했다. 보니까 Telegram -> OpenClaw 전달 경로 자체가 불안정한 것이 원인. Telegram 에서 메시지 보내도 응답이 없었다. 집가서 확인해보니 OpenClaw 프로세스 자체는 살아있었다. 그러나 telegram 쪽에서는 fetch fallback 이 반복되거나 polling 경로가 불안정한 로그가 존재했다.저번에 OpenClaw Gateway가 멋대로 죽었기도 했어서- OpenClaw Gateway 통신(rpc) 실패 시 즉시 restart- telegram degraded 연속적으로 실패할 때 restart두 곳에 대해 Watchdog 같은 것으로 Auto Restart 하도록 구성했다.### SSH, Control UI하지만 이것도 좀 불안하다. 내가 마주하지 못한 어떤 상황이 있을지 모르고 그래서 원격으로도 접근할 수 있도록 구성했다.Tailscale을 사용했다. Mesh VPN(P2P) 기반으로 동작한다고 한다. ssh 및 OpenClaw Control UI를 tailnet(vpn) oply로 열어, 외부에서도 상태 확인이나 직접 restart 가능하게 구성했다.### OpenAI Token Expired```⚠️ Agent failed before reply: OAuth token refresh failed for openai-codex: Failed to refresh OAuth token for openai-codex. Please try again or re-authenticate.Logs: openclaw logs --follow```그렇게 마음놓고 있었는데, 어느날 메시지 보내니 이런 응답이 계속 전달되었다. 이건 해당 PC에서 `openclaw models auth login --provider openai-codex` 명령으로 OpenAI 재로그인해 토큰 새로 발급받으면 해결된다. 문제는 그 로그인이 브라우저를 이용해야 한다는 것.그래서 이것도 결국 집에 와서야 고쳤다. 이건 조금 우회하는 방식을 이용했는데, TTL이 10일정도밖에 안되어서 Refresh Token 이용해 만료 3일 전부터 아래와 같은 시도 & 메시지 전달되게 했다.```md### 1. 알림 기준- 만료 3일 초과: 알림 없음- 만료 3일 전 ~ 1일 전: 24시간마다 알림- 만료 1일 이내: 6시간마다 알림- 이미 만료 후: 6시간마다 알림### 2. 알림 시각에 하는 일알림 시각이 오면, 순서는 항상:1. 현재 access token 만료 상태 확인2. refresh token으로 1회 재발급 시도3. 성공/실패와 상관없이 알림 발송4. 알림 본문에 refresh 결과 포함즉, **"알림 타이밍 = refresh 시도 타이밍"**### 3. refresh 결과 처리- 3일~1일: 하루 1번- 1일 이하/만료 후: 6시간마다성공- 알림은 반드시 1회 발송- 알림에: - 재발급 성공 - 이전 만료시각 - 새 만료시각- 다음 알림은 새 만료시각 기준으로 재계산됨- 이후에는 새 expiry 기준으로 다시 3일 전까지 조용히 대기실패- 알림은 반드시 1회 발송- 알림에: - 재발급 실패 - 가능하면 실패 사유/코드 - 현재 만료시각 또는 이미 만료 여부 - 재로그인 액션 안내 - 이후 cadence는 현재 상태 기준으로 계속```전달되는 메시지```[openclaw] Codex access token alert (1 day or less remaining)Model: openai-codex/gpt-5.4Profile: openai-codex:defaultChecked (KST): 2026-03-28, 3:15:50 p.m.Previous expiry (KST): 2026-03-28, 9:15:50 p.m.Previous remaining: 0d 12h 0mRefresh result: skippedRefresh detail: Dry run: refresh request not sent.Current expiry (KST): 2026-03-28, 9:15:50 p.m.Current remaining: 0d 12h 0mCurrent status: 1 day or less remaining```동작 성공도 확인했다 -> [OpenClaw 사용기(지속적인 업데이트)](/article/auwui-openclaw-review.html#260405)

AI 토큰 사용량을 확인해보니

shj — Fri, 20 Mar 2026 00:00:00 GMT

회사 Team 계정과 이전에 사두었던 카카오 OpenAI Pro 이용권 둘 모두 정말 잘 사용하고 있다.. 특히 카카오는 당시엔 이게 맞나 싶었는데 사두길 정말 잘했다. 보니까 달 토큰 사용량이 엄청나다.- codex: 1,113,853,377 + 2,018,202,308 + 152,085,882 + 224,970,824 = 3,509,112,391- claude: 1,295,991,757 + 1,043,799,657 = 2,339,791,414합쳐서 약 58억 개.. 시행착오가 많아지니 좀 더 어떻게 프롬프트 넣어야 하거나 어떻게 사용하는지 조금 감이 생기는 것 같다.

OpenClaw 사용기 (지속적 업데이트)

shj — Fri, 20 Mar 2026 00:00:00 GMT

# 260320OpenClaw 라는 것을 사용한지 4주정도 지났다. Telegram에 붙여 사용하고 있다. 처음에는 이걸로 뭘 해야할지 막막했는데 쓰다보니 조금 감이 잡힌다. 일단 실제 컴퓨터에서 돌아가는 Codex를 어디서든 사용할 수 있다는게 가장 편하다. 지금까지 아래 작업을 했다.- 일정 시간마다 CCTV 캡처해 고양이 어디에 있나 알림- OpenClaw 수리: 직접 사용해보니 예상과 다르게 동작한다거나, 지침이나, 망가졌을때 대비해서 계속 살려두거나, Codex Auth 토큰 만료전 알림이나, Telegram Topic으로 Chat 하기나, Codex CLI Local Skills 사용하기나, ... 그런 자잘한 손봐줘야 하는 부분들이 많다- 오픈소스, 툴 유지보수 (번역 관리 오픈소스 yuki-no, 기술 팟캐스트봇, url 요약봇 등)- 개인 프로젝트: 마음에 드는 기프티콘 관리 서비스가 없어 만들어보고 있다 / 이거 말고도 자신이 사용하는 AI 코딩 에이전트 환경 최신 가이드 잘 따르는지 확인/가이드/구성해주는 CLI 툴도 만들어보는 중- 그 외: 뭔가 있었는데 기억이 잘 안남출퇴근 할 때 chat 보내고 말해보카 하고 그러는데 뭔가 밀려드는 작업 쳐내는 느낌이라 뭔가 재밌다. 잘 쓰고있던 codex clarify skill 도 구성해뒀어서 애매한 질문해도 알아서 명확화해주니 편하기도 하다.슬슬 tts-stt 붙여서 좀 더 편하게 하고싶다는 마음도 있다. 가능성이 많은 툴이다. 가령 Telegram 으로 블로그 글 이렇게 쓸테니 그대로 업로드해달라거나..# 260405![codex-auth-rt](/images/auwui-260320/codex-auth-rt.png)Codex Auth Token 만료된다는 알람과, 실제 RT로 자동 갱신하는 로직이 잘 동작한다. 야호!

e2e codex skill w/ chrome-devtools-mcp

shj — Wed, 18 Mar 2026 00:00:00 GMT

## 시작요즘 구현 끝낸 뒤 chrome-devtools-mcp로 e2e 테스트를 진행하고 있다.```md/clarifychrome-devtools-mcp 를 이용한 e2e 테스트 계획을 세우자.대상은 refs/origin/develop 대비 현재 브랜치에서 변경된 모든 커밋/변경사항이야.어떤 방향으로 무엇(UI)을 테스트해야하고, 그것이 어떤 결과를 가져야 하는지 먼저 happy-path 를 구성해보자.진행 시 interrupts req + mock data 이용하는데, 절대로 기존 서버 req/res 구조를 변경해서는 안돼.서버 API 문서는 https://.../ 여기를 참고할 수 있어.또한 절대로 임의 추측/판단하지 말고, 반드시 실제 데이터/코드/문서/조사결과만을 바탕으로 진행하자.```## Codex Skills이 claude-code 프롬프트에서 시작해 지금은 codex 로 아래와 같이 스킬을 구성했다. ctx가 1M 이기도 하고, 5h/1w 한도가 널널해서 codex로 하기로 했다.

diff-aware-web-e2e

```md---name: diff-aware-web-e2edescription: Plan all impacted web E2E paths for current branch changes against a user-provided base ref, then execute only the user-selected paths with chrome-devtools-mcp. By default, use code-derived page-level request and response interception plus mock data unless the user asks for real API behavior. Use when the user wants evidence-based UI test planning and execution without changing server request or response contracts.---# Diff-Aware Web E2EUse this skill when the user wants to turn current branch changes into concrete, evidence-based web E2E checks.## What This Skill Does- Reads `...HEAD` changes to find impacted UI areas.- Produces a plan-level user product intent summary before scenario planning output.- Builds a full scenario inventory covering directly impacted user paths plus diff-backed edge-case and regression-focus checks.- Derives request and response shapes from code and docs before planning default interception and mock data.- States the planned mock target request, mock target response, and mock verification approach in plan output when API behavior matters.- Writes scenarios with step-by-step actions and step-by-step expected UI states.- Shows the full planned inventory, marks a recommended set with reasons, then asks the user which scenario IDs or recommended set to execute.- Optionally executes only the selected scenarios with `chrome-devtools-mcp`.- Automatically cleans up run-owned Chrome and `chrome-devtools-mcp` OS processes before any relaunch, after execution work, and after QA handoff markdown writing.- Renders QA handoff screenshots inline with Markdown image syntax `![]()` instead of plain file links.- Reports only evidence-backed results.## Default ModeStart in **plan-only** mode and do not execute until the user chooses which planned scenarios to run.## InputsCollect only what is missing:- `mode`: `plan` or `execute`- `base_ref`: required; compare `...HEAD`- `change_focus`: optional user concern or priority area- `target_area`: optional specific feature or page- `api_docs_url`: optional; use when provided- `mock_mode`: `auto` (default; use interception plus mock data unless the user says otherwise), `required`, or `off`## Core Rules- Never invent affected pages, API behavior, or expected results.- If `base_ref` is missing, ask the user for it and stop until it is provided.- Before the scenario inventory, provide a plan-level user product intent summary.- Build the user product intent summary from user input first, then supplement with defensible diff or related code evidence when needed.- Structure the user product intent summary using `Confirmed` and `Inferred`.- If product intent remains partially unclear, include `Open Questions` or `Unclear Intent` and continue planning when the scenarios are still defensible.- Keep the user product intent summary informative only; do not change scenario priority or recommended-set logic just because of it.- Derive every scenario from at least one concrete source: - changed code - tests or stories - API docs - observed browser or network evidence- Unless the user explicitly asks for real API behavior or `mock_mode: off`, treat chrome-devtools-mcp-based page-level request and response interception plus mock data as the default strategy.- Derive mock request and response shapes from code and docs before planning or executing page-level interception and mocking.- Plan the full impacted scenario inventory before suggesting execution.- Cover directly impacted user paths plus same-screen or same-flow paths, and include diff-backed edge-case and regression-focus scenarios when they are defensibly tied to the change.- Expand each planned path until a clear completion state is reached.- Include step-by-step user actions and step-by-step expected UI states.- When API behavior matters, say which request and response will be intercepted or mocked and how mock verification will be checked for each scenario.- Provide scenario IDs, priority, and a recommended set with reasons for planned paths.- Never auto-select or auto-execute the recommended set.- Do not change server request or response contracts.- Before any run-owned Chrome or `chrome-devtools-mcp` launch, briefly say that this skill will automatically remove the run-owned browser and MCP processes after work.- Cleanup targets are limited to run-owned Chrome, remote-debugging Chrome, and `chrome-devtools-mcp` OS processes started during the current chat and current skill invocation.- Before launching a replacement run-owned browser or MCP for recovery or QA capture work, clean up the current run-owned processes first.- After execution ends in `pass`, `fail`, or `block`, clean up run-owned Chrome and `chrome-devtools-mcp` OS processes before any follow-up result or QA handoff message.- If QA handoff writing needs additional captures, a new run-owned launch is allowed only after the current run-owned processes are cleaned up first.- After the QA handoff markdown file is written, clean up any run-owned Chrome and `chrome-devtools-mcp` OS processes before the follow-up message.- Treat cleanup as complete only when the owned OS processes are actually gone.- Briefly report cleanup success. If cleanup fails, briefly report that the run-owned browser or MCP process may still remain, then continue.- Never terminate `chrome-devtools-mcp`, Chrome, or remote-debugging processes that this run did not start.- If evidence is insufficient, ask or stop.## Evidence Order1. Changed code and tests2. Provided API docs3. Runtime DOM or network evidence4. User confirmationSee [evidence-rules.md](references/evidence-rules.md).## Planning Workflow1. If `base_ref` is missing, ask the user for it and stop.2. Read the diff against `...HEAD`.3. Find directly impacted UI entry points and related routes.4. Read only the minimal supporting code, tests, and docs needed to map the full impacted scenario inventory.5. Derive request and response shapes from code first by tracing the changed UI trigger, API caller, request builder, shared client, and response consumer.6. If `api_docs_url` is provided, inspect it to confirm endpoint purpose and response shapes.7. Before the scenario inventory, produce a plan-level user product intent summary that includes: - `Confirmed`: user-stated intent or intent made explicit in provided product context - `Inferred`: defensible intent inferred from the diff or related code - `Open Questions` or `Unclear Intent` when intent remains partially unresolved - brief evidence notes showing why each item is defensible8. For each scenario, produce: - scenario ID - coverage relation: `direct impact`, `same-screen branch`, or `same-flow regression` - scenario objective: `primary`, `edge-case`, or `regression-focus` - target UI or flow - why it is tied to the diff - ordered user actions - step-by-step expected UI states - request and response derivation evidence when API behavior matters - default execution strategy: mocked or real API fallback - mock target request and response when API behavior matters - mock verification plan - injection approach only when it is needed to explain feasibility - priority - recommended-set status and reason9. Show the user product intent summary, show the full scenario inventory, show the recommended set, and ask the user which scenario IDs or recommended set should move to execution.See [planning-rules.md](references/planning-rules.md).## Execution WorkflowUse this only after the user chooses which planned scenario IDs or recommended set to execute.1. Before any run-owned launch, briefly say that this skill will automatically remove the run-owned browser and MCP processes after work.2. If this same chat and skill invocation already owns run-owned Chrome or `chrome-devtools-mcp` OS processes from a prior attempt, clean them up before starting a replacement launch.3. Start a run-owned isolated Chrome and `chrome-devtools-mcp` context.4. Check that the current MCP runtime supports isolated execution, timeout tuning, and log capture. If that is clearly missing, report `block` with the missing preconditions.5. Do not attach cleanup behavior to any Chrome or MCP process not started by this run.6. Load the planned request and response derivation evidence together with the planned mock targets and verification checks.7. Unless the user opted out or the selected scenario was explicitly planned as a real API fallback, apply the planned page-level request and response interception and mock data with `initScript` or `evaluate_script` using only code-derived or doc-derived payload shapes.8. If needed, navigate to the selected target path.9. Wait for stable UI evidence before judging results.10. Use snapshots for structure and screenshots for reporting.11. Inspect console and network activity for corroborating evidence.12. On connection failure, retry in-place, then clean up the current run-owned browser and MCP processes, then start a replacement isolated run-owned instance, then collect logs and report `block` if recovery still fails.13. Determine `pass`, `fail`, or `block`.14. Clean up the run-owned Chrome and `chrome-devtools-mcp` OS processes before any follow-up result or QA handoff message.15. Briefly report the selected path result together with the cleanup status.Use these `chrome-devtools-mcp` capabilities when relevant:- `list_pages`- `select_page`- `new_page`- `navigate_page`- `wait_for`- `take_snapshot`- `take_screenshot`- `list_network_requests`- `get_network_request`- `list_console_messages`- `evaluate_script`See [execution-rules.md](references/execution-rules.md).## Mocking Policy- Unless the user explicitly asks for real API behavior or `mock_mode: off`, treat chrome-devtools-mcp-based page-level request and response interception plus mock data as the default strategy.- Planning should assume mocked execution first and describe the target request, target response, and mock verification approach for each scenario when API behavior matters.- Use code-first request and response derivation before deciding whether page-level mocking is safe.- First check whether page-level mocking is sufficient.- Page-level mocking may use `initScript` or `evaluate_script` to patch `fetch` or `XMLHttpRequest`.- For mocked flows, do not require a real network request as mandatory evidence.- Verify that mocking actually took effect using observable DOM evidence, explicit mock-hit evidence, or both.- Do not claim this is full browser-level interception.- If page-level mocking is unreliable or the scenario needs broader interception than it can safely cover, fall back to real API behavior or report `block`.## Output Format### Plan Mode- User product intent summary shown before the scenario inventory- `Confirmed`, `Inferred`, and `Open Questions` or `Unclear Intent` when needed- Evidence notes for the user product intent summary- Full impacted scenario inventory- Scenario ID, coverage relation, scenario objective, priority, and recommended-set status for each scenario- Recommended set with a short reason for each included scenario- Evidence for each scenario- Step-by-step actions- Step-by-step expected UI states- Request and response derivation evidence when API behavior matters- Default execution strategy- Mock target request and response when API behavior matters- Mock verification plan- Injection approach only when it is needed to explain feasibility- A final clarify step asking which scenario IDs or recommended set should move to execution### Execute Mode- Selected path result: `pass`, `fail`, or `block`- Run-owned cleanup status note- Screenshot- Brief evidence summary- Relevant network notes, or mock-hit notes for mocked flows- Mock verification notes- Recovery notes if connection handling was needed- A concise summary of the execution steps used to get to the result## Completion Wrap-Up- After all planned or selected execution work is complete, summarize the execution steps used: - diff basis - path selection logic - request and response derivation basis - execution setup - mocking approach - evidence collected - blockers or recoveries- If execution was performed, always ask whether to create a concise QA handoff document in Korean aimed at QA or planners.- If the user says yes, do not draft the QA handoff document yet.- First produce a concise QA handoff plan and ask the user to approve that plan before writing any file.- The QA handoff plan must include: - proposed `.md` save path with a single recommended location for user confirmation - intended audience - document section outline - scenario coverage to include - existing screenshots that are good enough to reuse - additional screenshots that must be captured or recaptured - device context for each screenshot: desktop or mobile - why each screenshot is needed for fast QA understanding- Do not draft the QA handoff document unless the user approves that QA handoff plan.- After the user approves the QA handoff plan, write the QA handoff as a `.md` file.- If QA handoff writing needs additional captures, start a new run-owned Chrome and `chrome-devtools-mcp` context only after cleaning up any current run-owned browser or MCP processes from this same chat and skill invocation.- After the QA handoff markdown file is written, clean up any run-owned Chrome and `chrome-devtools-mcp` OS processes before the follow-up message, and briefly report the cleanup status.- If the user asks for the QA handoff document, include: - write it in Korean for QA or planning audiences - scenario ID and title - goal - scope or covered user path in product terms - setup and mock strategy in audience-friendly terms - steps - expected UI - actual evidence - inline screenshots rendered with Markdown image syntax `![]()` and short captions, using element-focused captures with minimal surrounding noise when possible - network or mock verification notes - blockers or open risks- Exclude development implementation details, code-level explanations, internal reasoning, and backend contract discussion unless the audience explicitly asks for them.- Do not use plain file links as the primary screenshot presentation in QA handoff markdown.- Use full-page screenshots only when the element-focused capture would hide necessary product context.- Prefer screenshots that center the changed UI with only the surrounding context needed to understand the state.- Match screenshot device context to the product path being documented and say which captures are desktop or mobile.- If the existing screenshots are too broad, show the wrong device context, or do not make the changed UI easy to understand, take additional screenshots before drafting the QA handoff.## When To Stop And Ask- `base_ref` is missing- No reliable UI candidate can be tied to the diff- A completion path cannot be justified from code, docs, or observed behavior- Request or response shapes cannot be derived from code or docs without guessing- Code-derived request or response shapes conflict with observed runtime evidence- The planned scenario inventory is ready and user path selection is required- Mocking is required but safe scope is unclear- Authentication or setup prevents reliable execution- The user approved QA handoff creation and the QA handoff plan still needs approval- The proposed QA handoff save path needs user confirmation- Existing screenshots are not sufficient and additional capture scope still needs confirmation## Non-Goals- Branch-to-branch visual diff systems- App-wide route crawling unrelated to directly impacted paths- Full browser-level request interception guarantees- Mobile WebView-specific flows- Changing backend contracts to make tests easier- Killing externally managed Chrome or MCP processes```

`diff base 전달 - E2E 테스트 계획 - 시나리오 수립 - e2e 테스트 실행(ralph-loop) - QA 가이드 제안 - QA 가이드 작성(옵션, ralph-loop)` 이런 흐름으로 진행한다. diff 사이즈에 따라 다르지만, 시나리오 수립 후 실행하면 opus-4.6(thinking)/gpt-5.4(xhigh+fast) 기준 약 15~40분 정도 작업을 수행한다. 실행 단계에서는 끝까지 수행할 수 있도록 ralph-loop 를 잘 확용하면 좋다.그런데 따로 말해주지 않으면 claude-code 대비 findings(scenarios) 를 조금 덜 찾아준다.. 프롬프트를 좀 조정해 세부적으로 시나리오를 제공하도록 했다.chrome-devtools-mcp는 chrome bin 을 이용한다. 그래서 그런가 조금 자주 실패하기에(특히 `transport closed`), 실패 시 `재시도 - 현재 run-owned 정리 - replacement launch - 그래도 안 되면 로그 남기고 block & 알림` 이 순서로 상황 접근하도록 했다. 참고로 `transport closed` 는 단순히 mcp-브라우저 통신이 닫힌 상황.그래서 병렬 실행을 위해서도 조금 손봐야 한다. Shared browser 가 아닌 `isolated launch` 혹은 그에 준하는 ownership model을 사용하도록 해서 환경 자체를 분리해야 한다. 실행 끝나면 run-owned browser/MCP 정리까지 같이 가져가도록 한 건 그 연장선.`wait_for`는 페이지 진입 후 콘텐츠가 바로 보이지 않을 수 있기에(가령 SPA) 구성해줬다. Puppeteer 에도 이런 API가 있다.req/res는 기본적으로 가로채서 mocking한다. 특히 로그인 필요한 기능이 많아서 종종 핸드오프되기에... 계정(토큰)을 .env나 직접 전달하는건 조금 이상하기도 하고. 물론 이것도 계획에서 사용자에게 물어본다.재밌었던 점은 QA 가이드를 상당히 잘 만들어 준다는 점. QA 뿐만 아니라 기획자 등 비개발자에게 관련 내용을 전달할 때 매우 편했다. 어떤 점이 어떻게 변경되었고, 이를 어떻게 테스트할 수 있는지와 같은... 물론 이 역시 프롬프트에 존재한다. Execution 끝나면 QA 가이드 만들어줄지 물어보고, Yes 하면 세부적으로 계획을 세운다. `목적, 예상 범위, 예상 스크린샷` 중심으로 말해주고, 스크린샷도 markdown inline image로 정리하게 했다.### References docsreferences 디렉터리를 이용해 planning+evidence, execute 시 어떻게 접근해야 하는지도 문서화했다.

Planning Rules

```md# Planning Rules## ScopePlan the full impacted scenario inventory for changes in the current branch against `...HEAD`.Before the scenario inventory, provide a plan-level user product intent summary.Unless the user explicitly asks for real API behavior or `mock_mode: off`, planning should assume page-level request and response interception plus mock data as the default execution strategy.## User Product Intent SummaryCreate a single plan-level summary before the scenario list.Use these fields:- `Confirmed`: intent explicitly stated by the user or made explicit in provided product context- `Inferred`: defensible intent inferred from the diff or closely related code- `Open Questions` or `Unclear Intent`: unresolved gaps that do not block a defensible scenario planIntent evidence should prefer user input first and use diff or related code only as supporting evidence.Do not change scenario priority or recommended-set logic based on this summary alone.## Candidate UI SignalsUse these signals to infer impacted UI:- route or page files- router config- changed components imported by pages- button, heading, link, or `data-testid` strings- tests, stories, or Playwright specs## Scenario TaxonomyEvery scenario must include both labels:- `coverage relation`: `direct impact`, `same-screen branch`, or `same-flow regression`- `scenario objective`: `primary`, `edge-case`, or `regression-focus`Use defensible pairings:- `primary` usually covers the main changed path and commonly pairs with `direct impact`- `edge-case` covers alternate, boundary, empty, error, or validation states that are defensibly tied to the diff and commonly pairs with `direct impact` or `same-screen branch`- `regression-focus` covers behavior that should remain stable around the changed path and commonly pairs with `same-screen branch` or `same-flow regression`If a scenario needs an unusual pairing, explain why that pairing is justified by the diff or supporting code.## Code-Based Request And Response DerivationWhen API behavior matters, derive request and response shapes from code first:1. identify the changed UI trigger2. find the action handler or event path3. trace the API caller or shared client4. inspect request builders, params, payload keys, and headers5. inspect response consumers, branch conditions, and rendered UI states6. use API docs only to confirm or supplement what code already supports7. use runtime network evidence only to verify or compare against the code-derived understandingIf code and docs do not support a request or response shape, do not invent one.## Scenario ConstructionFor each scenario, include:- scenario ID- coverage relation- scenario objective- target page or flow- changed code evidence proving why the scenario is tied to the diff- start point- completion condition- step-by-step user actions- step-by-step expected UI states- request and response derivation evidence when API behavior matters- default execution strategy: mocked or real API fallback- mock target request and response when API behavior matters- mock verification plan- injection approach only when it is needed to explain feasibility- priority- recommended-set status and reason- confidence and any assumptions that still need user confirmation## Path Expansion- Expand each directly impacted path until the user reaches a clear completion state.- Do not stop at the first changed screen if the affected flow continues.- Include same-screen branches and same-flow regression checks when they are defensibly tied to the changed path.- Include separate diff-backed `edge-case` and `regression-focus` scenarios when the changed path exposes them.- Do not broaden into unrelated feature-wide regression coverage.## Documentation Use- If `api_docs_url` is available, use it to confirm endpoint purpose and response shape after tracing the code path.- If no docs are available, rely on code first and runtime evidence only as supporting verification.- If neither code nor docs support an expected API outcome, do not invent one.## Question PolicyAsk only when a missing fact blocks a defensible plan.If `base_ref` is missing, ask for it before reading the diff.If request or response shapes cannot be derived from code or docs without guessing, ask before planning mocks.If code-derived request or response shapes conflict with runtime evidence in a way that changes the scenario expectation, ask before continuing.If mocked execution looks unsafe or unsupported for the scenario and no defensible real API fallback is available, ask or plan the scenario as `block`.If user product intent is only partially clear but the impacted scenarios are still defensible, continue planning and record the gaps under `Open Questions` or `Unclear Intent`.After presenting the full planned scenario inventory and recommended set, ask the user which scenario IDs or recommended set should move to execution.```

Evidence Rules

```md# Evidence Rules## Allowed Evidence- changed source files- tests and stories- official API docs when provided- observed DOM state- observed network requests and responses- observed console output- explicit mock-hit markers exposed by the patched page layer## Path Coverage Standard- The planning result should account for all directly impacted user paths that can be justified from the diff and supporting code.- The planning result should also account for same-screen branch and same-flow regression scenarios when they are defensibly tied to those directly impacted paths.- The planning result should include separate diff-backed `edge-case` and `regression-focus` scenarios when the changed path exposes them.- Each planned path should explain why it is tied to the change and why its coverage relation and scenario objective are justified.- When API behavior matters, each planned path should also say which request and response will be mocked by default and how mock confirmation will be checked.## Disallowed Behavior- inventing routes or user flows- inventing response fields not supported by code or docs- inventing mock payloads not supported by code or docs- claiming pass or fail without a visible or observable signal- changing backend request or response contracts- claiming mocking worked without observable confirmation- requiring a real network request as mandatory proof for a page-level mocked flow## Reporting StandardEach conclusion should be traceable to one or more concrete observations.Each step-level expected UI state should be traceable to code, docs, tests, or observed behavior.When planning a mocked flow, the report should name the intended mock target request, intended mock target response, and mock verification approach in concise scenario-level terms.For page-level mocked flows, acceptable confirmation may come from DOM state, explicit mock-hit markers, console markers, or a real network request when one still occurs.For QA handoff screenshots, prefer relevant element-focused captures with minimal surrounding noise. Use broader page captures only when the focused capture would hide necessary product context.For QA handoff screenshots, the chosen capture should make the changed UI easy to understand quickly for QA readers, not just prove that the page existed.For QA handoff screenshots, match the capture to the documented device context, including desktop versus mobile.If an existing screenshot is too broad, lacks the changed UI focus, or shows the wrong device context, treat it as insufficient and capture a better one before drafting the QA handoff.If code-derived request or response shapes conflict with runtime evidence, say so and stop or report `block` instead of guessing.The final report should also include a short execution-step summary describing how the result was reached.If confidence is low, say so and explain what evidence is missing.```

Execution Rules

```md# Execution Rules## Browser Strategy- Each execution owns its own isolated Chrome and `chrome-devtools-mcp` context.- Never terminate Chrome, remote-debugging Chrome, or `chrome-devtools-mcp` processes that this run did not start.- If the user needs to log in manually inside the isolated run-owned browser, pause and resume after the handoff.## Run-Owned Cleanup- Before any run-owned Chrome or `chrome-devtools-mcp` launch, briefly tell the user that this skill will automatically remove the run-owned browser and MCP processes after work.- Cleanup scope is limited to run-owned Chrome, remote-debugging Chrome, and `chrome-devtools-mcp` OS processes started in the current chat and current skill invocation.- Before any replacement launch for recovery or QA captures, clean up the current run-owned browser and MCP processes first.- Attempt cleanup on every execution end state: `pass`, `fail`, or `block`.- After the QA handoff markdown file is written, clean up any remaining run-owned browser or MCP OS processes before the follow-up message.- Treat cleanup as complete only when the owned OS processes are actually gone.- On cleanup success, say briefly that the run-owned browser and MCP processes were removed.- On cleanup failure, say briefly that cleanup failed and the run-owned browser or MCP process may still remain, then continue.## Preflight- Before execution, verify that the active MCP runtime is configured for isolated launches or another equally safe ownership model.- If the runtime clearly lacks isolation, timeout tuning, or log capture, report `block` and name the missing preconditions.## MCP Tool Usage- Use `take_snapshot` to inspect page structure before acting.- Use `wait_for` for stable UI evidence instead of fixed sleeps when possible.- Use `take_screenshot` for final reporting artifacts.- Use `list_network_requests` and `get_network_request` to confirm real API activity or compare against the code-derived understanding when real requests occur.- Use `list_console_messages` to spot frontend regressions or collect explicit mock-hit markers when available.- For QA handoff screenshots, prefer element-focused captures with minimal surrounding noise and use full-page captures only when broader product context is necessary.- For QA handoff markdown, render screenshots inline with Markdown image syntax `![]()` instead of plain file links.- Before drafting a QA handoff document, review whether the existing screenshots clearly show the changed UI state for the intended audience.- If an existing screenshot is too broad, hides the changed UI, or uses the wrong device context, recapture it.- Match the screenshot viewport and framing to the documented product context, including desktop versus mobile.## Connection Recovery- On `transport closed` or similar MCP connection failures, retry once or twice in the current run-owned context.- If retry fails, clean up the current run-owned browser and MCP processes, then recreate the isolated run-owned Chrome and MCP context and continue.- If recovery still fails, enable log capture, preserve the failure evidence, and report `block`.- Prefer explicit logging and timeout tuning over silent retries.- When the client configuration allows it, raise `startup_timeout_ms` and capture `--log-file` output for failed runs.- Prefer isolated run-owned launches over auto-connecting to external browsers for parallel execution.## Result Labels- `pass`: expected UI and supporting evidence match- `fail`: expected UI or supporting evidence clearly diverge- `block`: missing auth, missing data, unsupported mocking, insufficient evidence, or unresolved code versus runtime conflicts## Mocking- Unless the user explicitly asks for real API behavior or `mock_mode: off`, request and response interception with mock data is the default strategy.- Follow the planned mock targets and mock verification checks from plan mode unless runtime evidence forces a safer fallback.- Derive request and response shapes from code and docs before writing any mock payload.- Page-level mocking may patch `fetch` and `XMLHttpRequest`.- For mocked flows, a real network request is optional evidence, not mandatory evidence.- Confirm that mocking took effect with observable DOM evidence, explicit mock-hit evidence, or both.- Treat explicit mock-hit evidence as something the patched layer exposes and can be checked with the page or console state.- Do not present page-level mocking as complete interception coverage.- If the flow depends on navigation requests, service workers, or subresource control, treat that as unsupported unless the project already provides a safe mechanism.- If the planned mock target cannot be intercepted safely at the page level, fall back to real API behavior only when the selected scenario still stays evidence-based; otherwise report `block`.- If request or response shapes cannot be derived without guessing, stop and ask instead of inventing payloads.- If code-derived request or response shapes conflict with observed runtime behavior in a way that changes the selected scenario, stop and ask or report `block`.```

### `agents/openai.yaml`implicit invocation 시 어떤 prompt로 진입할지, 그리고 어떤 순서로 정리할지 명시된 파일. `base_ref` 요구, full scenario inventory, cleanup, QA handoff plan 선행, inline screenshot 규칙까지 이 파일에 같이 녹여뒀다.

openai.yaml

```yamlinterface: display_name: 'Diff-Aware Web E2E' short_description: 'Plan all impacted paths, then execute chosen ones' default_prompt: 'Use $diff-aware-web-e2e to ask me for the required base_ref, plan the full impacted web E2E scenario inventory for current branch changes against ...HEAD, derive request and response shapes from code before proposing mocks, include diff-backed edge-case and regression-focus scenarios, recommend a scenario set, then help me choose which scenarios to execute. Before any run-owned Chrome or chrome-devtools-mcp launch, briefly say that this skill will automatically remove its run-owned browser and MCP processes after work. If a relaunch is needed for recovery or QA captures, clean up any current run-owned browser and MCP processes first. After execution finishes in any result state, clean up the run-owned browser and MCP before follow-up messages or QA handoff questions. If I say yes to QA handoff, do not draft it yet. First propose a concise QA handoff plan with a recommended markdown save path, section outline, screenshot reuse versus recapture plan, and desktop or mobile capture context, then wait for my approval before writing the file. When you write the QA markdown file, render screenshots inline with Markdown image syntax ![]() instead of plain file links, and after the file is written, clean up any run-owned browser and MCP processes again before the follow-up message.'policy: allow_implicit_invocation: true```

## 팀> 이 스킬 만들 때는 나오지 않았었는데, Codex 도 3월 28일부터인가 Marketplace 를 지원해서 이쪽으로 이동해야 한다...혼자 사용하면 재미없고 발전이 없기에 팀 ai 활용사례? 리포지토리에도 올렸다. 가이드와 함께 설치/검증 스크립트를 제공했다.

Installation

Verification

```sh#!/usr/bin/env bashset -euo pipefailSCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"SOURCE_DIR="${REPO_ROOT}/skills/diff-aware-web-e2e"TARGET_DIR="${HOME}/.codex/skills/diff-aware-web-e2e"hash_file() { local file_path file_path="$1" if command -v shasum >/dev/null 2>&1 then shasum -a 256 "${file_path}" | awk '{print $1}' return fi if command -v sha256sum >/dev/null 2>&1 then sha256sum "${file_path}" | awk '{print $1}' return fi echo "Error: neither shasum nor sha256sum is available." >&2 exit 1}hash_stdin() { if command -v shasum >/dev/null 2>&1 then shasum -a 256 | awk '{print $1}' return fi if command -v sha256sum >/dev/null 2>&1 then sha256sum | awk '{print $1}' return fi echo "Error: neither shasum nor sha256sum is available." >&2 exit 1}dir_manifest_hash() { local dir_path dir_path="$1" ( cd "${dir_path}" find . -type f | LC_ALL=C sort | while read -r relative_path do local_hash="$(hash_file "${dir_path}/${relative_path#./}")" printf '%s %s\n' "${local_hash}" "${relative_path}" done ) | hash_stdin}if [[ ! -f "${SOURCE_DIR}/SKILL.md" ]]then echo "Error: source skill file not found: ${SOURCE_DIR}/SKILL.md" >&2 exit 1fiif [[ ! -d "${TARGET_DIR}" ]]then echo "Error: target skill directory not found: ${TARGET_DIR}" >&2 echo "Run: ./scripts/install-diff-aware-web-e2e-skill.sh" exit 1fiSOURCE_HASH="$(dir_manifest_hash "${SOURCE_DIR}")"TARGET_HASH="$(dir_manifest_hash "${TARGET_DIR}")"echo "Source: ${SOURCE_DIR}"echo "Target: ${TARGET_DIR}"echo "Source manifest SHA-256: ${SOURCE_HASH}"echo "Target manifest SHA-256: ${TARGET_HASH}"if [[ "${SOURCE_HASH}" == "${TARGET_HASH}" ]]then echo "Status: synchronized" echo "Standard usage: \$diff-aware-web-e2e " exit 0fiecho "Status: mismatch"echo "Run: ./scripts/install-diff-aware-web-e2e-skill.sh"exit 2```

Yuki-no 플러그인과 AI 에이전트를 이용해 2800 라인 Diff 하루만에 번역하기

shj — Fri, 08 Aug 2025 00:00:00 GMT

# TL;DR- .## 1. 번역 프로젝트와 딜레마- 나는 Vite에 [한국어 문서 번역 프로젝트](https://github.com/vitejs/docs-ko/) 메인테이너로 기여하고 있다 - 이를 진행하며 다양한 상황을 맞닥뜨렸고, 하나씩 해결해 갔었다 - 여기서는 기존 번역 방식에 대한 한계 및 해결에 대해 다뤄본다- 앞서 [Cursor 이용한 번역 경험](./translate-to-korean-with-cursor.html)이나 [Yuki-no 개발기](./starting-technical-documentation-translation-project-with-github)에서도 언급했듯 - 빠르게 변화하는 오픈소스 문서를 번역한다는 것은 전문가가 아닌 이상 적지 않은 리소스를 꾸준하게 투자하는 건 쉽지 않은 일이다### 기존 워크플로우 문제점### 왜 자동화가 필요한가## 2. Yuki-no 플러그인 시스템 & [@yuki-no/plugin-batch-pr](https://npmjs.com/package/@yuki-no/plugin-batch-pr)### 플러그인 아키텍처### [@yuki-no/plugin-batch-pr](https://npmjs.com/package/@yuki-no/plugin-batch-pr)## 통합 워크플로우### 4단계 자동화 프로세스### 단계별 도구 및 역할## 4. 결과 분석### Before/After### ROI## 5. In Action### 설정 방법### 템플릿## 6. 마치며---S:- 나는 Vite에 한국어 문서 번역 메인테이너로 기여중- [Cursor로 Vite 한국어 문서 번역 진행한 경험](./translate-to-korean-with-cursor.html)이나 [GitHub으로 기술 문서 번역 프로젝트 시작하기](./starting-technical-documentation-translation-project-with-github)에서도 언급했지만 - 번역은 지속적으로 리소스 부어야 하고 - 상대적으로 은근히 꾸준하게 리소스가 들어가는 작업 - 왜? Vite는 많이 바뀌는데 이걸 처리하는 인원은 상대적으로 많지는 않으니- 저 이후 번역할 때 AI를 많이 사용하는데 그래도 뭔가 비효율적이더라- 프로세스를 설명하자면 이런데 - 이슈에서 번역 관련 변경사항 확인 - 번역 리포지토리에 해당 내용 번역해 집어넣음 - 커밋 & push - 좀 별로임 이거..T:- 이게 문제점이 있음 - 순차적으로 해야하는데, 이러다보니 이후 변경사항에서 삭제되거나 내용이 바뀌는 경우가 있음 - 근데 왜 순차적이냐, 히스토리를 따라가야 변경사항 제대로 반영되기에 - 그래서 무의미한 리소스 소모가 많았음 - 그렇다고 한번에 모두 반영하고 번역돌리자니 귀찮았음 - 양이 적은것도 아니고 얼마나 걸릴지 모르는데 로컬에서 작업하고 있다가 외부에서 기여가 들어오면? - assign 해두면 되긴 하지만 이런 과정들이 번거롭고 귀찮았음 - 일부만 하면 된다, 한번에 날 잡고 하면 되지 않냐 다양한 방법이 떠오를 수 있겠지만 - 그냥 그런 과정 모두가 귀찮았음 무의미한 리소스 쏟는 느낌이었고- 그렇게 번역하다 어느순간 여기서 벗어나야겠다는 생각이 듦 - 그렇게 [Yuki-no](https://github.com/Gumball12/yuki-no/) 다음 버전을 만들어야겠다 생각함 - 6월 25일부터 작업 진행했고, 8월 7일 어제 작업이 어느정도 완료되어서 - 이를 이용해 약 2800 라인 Diff를 번역 관련 번경 사항을 하루만에 작업 완료했음- 여기서는 내가 뭘 만들었고 어떻게 번역 작업했는지 소개하고자 함 - 이걸 바탕으로 다른 번역 리포지토리에도 소개할건데 바로 In Action 하고자 한다면 [이 섹션](#)으로 이동하길 바람A(yuki-no):- 먼저 Yuki-no 자동화임 - 자동화는 이전부터 생각해왔었음 - 다만 어떻게 접근하면 좋을지 고민하다 이전에 개발한 Yuki-no를 확장해보면 어떨까 하는 생각이 듦- 이를 위해 먼저 확장성을 다시 생각해보자 생각했음 - 어차피 취미로 하는 프로젝트고 이전부터 생각했던 GitHub Actions에서 플러그인 시스템을 도입해보고자 생각도 했어서 - 앞으로도 새로운 기능 도입될텐데 플러그인으로 서로 독립적으로 구성할 수 있으면 좋겠다 생각햇음 - 또 GitHub Actions에서 플러그인 시스템을 구축한 사례를 못봐서 - 왜 없었을까?- 깊이 다루지는 않겠지만 간단히 다음과 같은 시스템으로 구성함 - (그림) - Yuki-no 라이프사이클을 만들고 각 지점마다 호출되는 훅에 대한 인터페이스 정의 - 그리고 플러그인 목록을 action으로 전달받아 이를 Yuki-no 시작 전 npm 레지스트리에서 설치해 사용- 덕분에 핵심 로직만 core로 남길 수 있었고 - 릴리스 추적이나 이번에 개발한 배치 PR 기능을 플러그인으로 성공적으로 분리할 수 있게 됨 - 이후 AI 번역도 추가할 계획이라 플러그인 분리가 적절했다고 생각되었음 - 이를 쉽게 배포하기 위해 [cd 파이프라인](https://github.com/Gumball12/yuki-no/blob/next/.github/workflows/publish.yml)도 조금 손봤고- 릴리스 추적은 [GitHub으로 기술 문서 번역 프로젝트 시작하기](./starting-technical-documentation-translation-project-with-github) 블로그 글에서 설명하고 있음 - 이건 [@yuki-no/plugin-release-tracking](https://npmjs.com/package/@yuki-no/plugin-release-tacking) 이라는 이름으로 npm 배포했고 - 하위호환성 지키는 로직도 구성함- 그럼 배치 PR은 뭐냐 - 앞서 번역 프로세스에서도 언급했는데 - 번역 관련 변경 사항을 번역 리포지토리에 모두 적용시키는 기능만을 담당하는 플러그인임 - 리포지토리 A에 존재하는 커밋 중 일부(번역 관련)만 취해서 이를 리포지토리 B에 적용시키는 것 - 단순히 변경사항을 이동시키는건 아니고 몇 가지 고려사항이 있음 - 루트 디렉터리가 다를 수 있음 - 실제로 vite 한국어 문서가 그랬는데 - 원본 리포지토리에서는 문서 관련 내용이 docs 디렉터리 아래에 있었는데([vite/docs/](https://github.com/vitejs/vite/tree/main/docs/)) - 번역 리포지토리에서는 루트에 문서 관련 내용이 있었음([docs-ko/](https://github.com/vitejs-docs-ko/)) - 그래서 이를 지정할 수 있도록 해야 함 - 또한 수동으로 적용해야 하는 변경 사항이 있을 수 있음 - package.json이나 관련 설정이나 의도적으로 수동으로 관리하는 문서 등 - 마지막으로 "실제로 무엇이 변경되었는지" diff를 확인해서 이동시켜야 함 - 단순히 파일 단위로 이동시키면 기존 번역 내용이 모두 날아가기 때문 - 이것도 간단하게 설명하자면 - 수동으로 적용해야 하는 변경 사항은 기존 picomatch 기반 작성한 함수 있어서 이를 그대로 이용 - 변경사항 적용은 로직을 구현해야 했는데 크게 2가지로 분리해서 진행함 - (생각해보니 이것도 npm 라이브러리로 만들어도 좋을듯, 아니면 이미 있으려나?) - git diff에서 변경사항을 추출해 `FileChange`라는 데이터 구조로 만드는 `extractFileChanges` - `FileChange` 배열을 전달받아 이를 통해 실제 파일을 수정하는 `applyFileChanges` - 아무튼 이렇게 구현했고 [@yuki-no/plugin-batch-pr](https://npmjs.com/package/@yuki-no/plugin-batch-pr) 이라는 플러그인으로 만들어 npm 배포 완료R(yuki-no):- 그렇게 지금 vite 한국어 번역 문서 프로젝트를 alpha test 필드로 삼아 해봤는데 잘 굴러가고 있는 것 같다 - 몇 가지 개선사항이 있긴 하지만 - 수동으로 관리하고자 하는 목록을 pr body에 보여준다던가 - pr 안만들어도 되는 상황에서는 만들지 않는다던가 등 - 그건 차차 추가하기로 하고, 가장 핵심 기능인 변경사항 모두 취합해 PR 하나로 만들어주기 기능은 잘 동작하는 것으로 보임- vsc + cline ext + claude code - claude max 플랜 구독해 claude code 바탕으로 sonnet-4와 opus-4 번갈아 사용 - cursor 쓰다가 너무 사용량이 부족해 claude max 플랜에 vsc에 [cline](https://cline.bot/) 이라는 오픈소스 익스텐션 붙여서 사용중 - 여기에 sequential thinking, tavily, file system, context7 정도만 mcp 붙이고 - 커뮤니티와 ai 도움받아 작성한 cline rules 바탕으로 사용중 - 물론 cursor가 20 플랜이긴 해도 좀 많이 심각하게 부족했음 - 한동안은 이 형태로 가지 않을까 - conductor도 써봤는데 토큰과 cost를 너무 많이 소모해서 별로 - 동일한 mcp 붙여서 사용했는데 내부 프롬프트가 좀 다른듯- 근데 sonnet-4 위주로 사용하긴 했지만 완벽하진 않더라 - 특히 코드베이스를 결국 이해해야 한다는 건 마찬가지였음 - 케이스 찾아보기 어려운 특정 버그는 거의 도움을 받기 어렵더라 - 대신 코딩&디버깅 시간보다 리뷰 시간이 이전에는 9:1이었다면 지금은 2.5:7.5정도가 된 느낌- claude code pr review - cc에서 first-party로 제공하는 기능인데 꽤 좋았음 - 로컬에서 사용중인 cline rules 바탕으로 pr review rule 만들고 - github action 이용해 pr review 하도록 [파이프라인](https://github.com/Gumball12/yuki-no/blob/next/.github/workflows/claude.yml) 구성해서 가능한데 - 나는 추가로 `@claude ` 라는 코멘트 붙었을 때만 pr review 하도록 구성함 - 아무튼 상당히 구체적이고 다각적으로 코드 분석해줘서 - 실제로 구현한 코드에서 놓쳤던 부분(로컬에서 한번 cc로 검증 거쳤음에도 있었다)도 - 얘가 잡아주기도 했음A(translation):- 그래서 이렇게 개발한 batch-pr 플러그인으로 번역 필요한 모든 변경사항을 하나의 PR로 자동으로 모을 수 있게 되었음 - 아직 정식 배포는 아니고 wip 버전으로 지금 vite 한국어 번역 프로젝트에서 사용중이지만 - 한 달 정도 보고 정식 배포 진행할 예정- 이렇게 만든 pr은 https://github.com/vitejs/docs-ko/pull/1268 에서 확인할 수 있음 - batch-pr 결과: https://github.com/vitejs/docs-ko/compare/a34c8d7bd4beb9e68d3b3349ffed94c96b2b11c1..68afebcd27172dd65b557069a3d6e3b26f166889 - missing contents: https://github.com/vitejs/docs-ko/pull/1268/commits/cc017a35ce02306622336182a5f2231dcc2a98d9 - 지금은 해결된 버그로 인해 누락된 .vitepress 디렉터리 아래 변경사항과 - 의도적으로 포함시키지 않도록 설정한 파일을 반영- 이는 git history에 존재하고, 이 diff를 바탕으로 cc로 1차 번역 해달라고 했음 - https://github.com/vitejs/docs-ko/pull/1268/commits/6dee54f88f17fc86a7317c3fe5f748225e10ef1a - 당연히 이게 완벽하진 않아서 내가 리뷰 한번 거치긴 했다만 - 룰을 좀 더 상세하게 정해서 번역하도록 하면 리뷰를 조금 덜 수 있을 것 같음 - (프롬프트 파일) - 이를 위한 ai 에이전트나 특정 툴에서 독립적인 룰 파일도 만들었다 - 이걸 참고해서 번역하라 할건데 잘 동작하는지는 지켜볼 예정- 이후 리뷰 내용을 바탕으로 AI & 수동으로 수정했고 - 엄청 많지는 않아서(작은 범위 단위 53개 정도), 5시간정도 소모해 번역 모두 완료했다 - 대부분 번역이 잘 되어서 그냥 원문과 함께 한번 읽어보고 이상하게 다가오는 부분만 교정해줌- 총 5~6시간 정도 걸려서 엄청 많은 변경사항(81개, 2800라인/68파일 Diff)에 대한 번역 완료했다 - 결과물도 꽤 만족스러웠음R(translation):- 처음보다 조금 길어지기는 했지만 프로토타입 버전은 잘 만들어졌다 생각함 - 기존 리소스를 많이 차지하는 부분을 자동화한 부분이 상당히 컸음 - 원래 방식대로 진행했다면 1주일 조금 더 걸리지 않았을까 - 하는것도 재미없었을거고 스트레스만 되었을거고- 이후 1차 초벌 번역 플러그인도 만들 예정이다 - 이것도 자동화 가능해보임 - 다만 먼저 홍보부터 하고.. (ai 번역 플러그인 넣는다 해도 ai 구독 필요한데, 이건 일단 구현없이도 로컬이지만 가능해서)- 최종적으로는 내가 리뷰만 하고 리뷰 바탕으로 AI가 추가 수정하거나 내가 직접 수동으로 수정해서 - 리소스를 최소화할 예정 - 이로 인해 외부 기여는 많이 줄어들지 않을까 (리소스 필요한 부분이 많이 덜어졌으니)- 또한 더 나아가 비슷하게 번역 프로젝트 관리하는 데 힘 부치는 사람들 위해서 이거 도입을 도와주고 싶다 - 분명 나처럼 매너리즘 빠졌거나 힘들텐데 도움이 될 수 있으면 좋겠다 - 도울 수 있는게 있을지 모르니 필요하면 언제든 편하게 연락주라R(conclusion):- 그 외로 개발에 cc를 많이 사용했다 - (사진) - 큰 의미는 없지만 claude $100 max 사용중인데 만약 api로 같은 작업 했다면 약 $1000 이상 사용했을거라고 찍힌다 - 상당히 도움이 되었고- 그리고 몇 주 전에 cc subagents 나왔다고 하던데 cc pr review 비슷한건가? - 사용 예시를 보았지만 크게 다가오지는 않고 완전 100% vive 코딩을 하는건 아니어서(결국 리뷰해야하는) conductor와 함께 사용 안하는 툴이 되긴 했지만 - 이렇게 빨리 ai 툴 나오고 그런거 보면 사용 예시 보면서 무엇을 할 수 있는지 간단하게라도 계속 보는게 중요한 듯- 퇴사 후 8개월, 이제 모아둔 돈도 슬슬 떨어지고 어쨌든 수입이 필요한 상황임 - 아마 회사를 들어가게 될 것 같은데, 백수생활 청산하면 이런 경험을 바탕으로 생산성 많이 끌어올려보고싶다

GitHub으로 기술 문서 번역 프로젝트 시작하기

shj — Fri, 14 Feb 2025 00:00:00 GMT

# GitHub으로 기술 문서 번역 프로젝트 시작하기기술 문서 번역은 더 많은 사람들이 접근할 수 있도록 돕는 중요한 일이다. 해당 언어에 익숙하지 않은 사용자들이 새로운 기술을 배우고 적용할 수 있도록 많은 도움을 준다. 특히 오픈소스 프로젝트에 대해서는 기술 생태계를 확장하고, 더 많은 개발자들이 프로젝트에 기여할 수 있는 기회를 제공한다.나는 현재 [Vite](https://vitejs.dev)의 [한국어 문서 번역 프로젝트](https://github.com/vitejs/docs-ko) 메인테이너로 활동하고 있다. Vite는 매우 빠른 속도로 발전하는 차세대 프런트엔드 빌드 툴로, 매일 수많은 업데이트가 이루어진다. 이 글은 활발하게 개발되는 프로젝트에 대한 문서를 번역할 때 발생할 수 있는 문제와, 이를 해결하기 위해 개발한 [Yuki-no](https://github.com/Gumball12/yuki-no)라는 오픈소스를 소개하기 위해 작성했다.# The Problems번역 프로젝트는 여러 형태로 구성이 가능하다. [Crowdin](https://crowdin.com/)과 같은 상용 서비스를 이용하거나, [VitePress](https://vitepress.dev/)나 [Docusaurus](https://docusaurus.io/)와 같은 i18n을 지원하는 오픈소스 문서화 솔루션을 이용할 수 있다. 어떤 방법을 선택하든, 번역 작업은 원본 문서 변경에 대한 추적이 매우 중요하다. 그렇지 않으면 잘못된 부분을 번역하거나, 번역이 필요한 내용 중 일부를 빠트릴 수 있다.Vite를 막 번역하기 시작했을 때 나는 이에 대한 중요성을 잘 알지 못했다. 원본 문서 특정 버전(커밋)을 목표로 번역을 진행했었는데, 절반 정도 진행하니 몇 문제들이 발목을 잡았다.- **원본 문서와 차이점이 발생**: 원본 문서는 계속 업데이트된다. 새로운 기능 설명이 추가되거나 API가 변경되면서 이미 번역한 내용이 종종 구버전이 되어버렸다.- **필요하지 않은 부분을 번역**: 최신 문서에서는 이미 삭제되었거나 변경되었는데, 이를 모르고 번역해버려 시간을 낭비했다.- **번역 참여자들에게 설득이 어려움**: "왜 이 버전에 대해 번역을 진행해야 하나요?"라는 질문에 적절한 답변을 제공하기 어려웠다. 어떻게 답변을 했지만, 스스로 납득되지 않았다.모두 원본 문서와 동기화를 수행해주지 않아 발생한 문제다.## 수동으로 관리하기![수동으로 관리하기](/images/250214/with-manual.png) _번역 프로젝트 작업 흐름_처음에는 수동으로 동기화 작업을 진행했는데, 상당히 비효율적이었다:1. **시간 소모적인 확인 작업**: 주기적으로 원본 저장소에 변경 사항이 있는지 수동으로 확인해야 했다.2. **릴리스 상태 파악**: 변경된 내용이 실제 릴리스된 기능인지, 아직 개발 중인 베타 기능인지 일일이 확인해줘야 했다.3. **이슈 생성과 추적**: 번역이 필요한 부분을 찾아 이슈로 생성하고, 해당 이슈를 추적하는 과정도 모두 수동으로 진행했다.이러한 변경 사항을 확인하고 이슈로 만드는 작업이 단순해 보이지만 실제로는 상당히 귀찮고 시간을 소모하는 일이다. 실제로 번역 자체보다 프로세스 관리에 더 많은 시간을 쏟게 되어 원활한 진행을 어렵게 만드는 요소 중 하나였다. 게다가 수동 작업 중 실수로 변경 사항을 놓치는 경우도 종종 발생했는데, 이럴 때는 정말 지루하고 의욕이 떨어졌다.이러한 문제들을 효율적으로 해결하기 위해서는 동기화 과정을 자동화할 필요가 있었다.# Ryu-Cho 도입![Ryu-Cho 도입](/images/250214/with-ryu-cho.png) _Ryu-Cho는 원본 저장소에 대한 새로운 변경 사항을 이슈로 만들어준다_한계를 느낀 나는 (그제서야)다른 번역 프로젝트를 둘러보았다. React 진영은 직접 [스크립트를 작성](https://github.com/reactjs/translations.react.dev)해 중앙 집중식으로 관리하고 있었고, Vue 진영은 오픈소스를 이용해 각 번역 프로젝트에서 동기화를 수행하고 있었다. 최종적으로는 Vue 및 다른 Vite 번역 프로젝트에서 사용하는 [Ryu-Cho](https://github.com/vuejs-translations/ryu-cho)라는 오픈소스를 도입했다. 제공하는 기본적인 기능은 다음과 같다:- 원본 저장소 커밋 모니터링- 새로운 커밋에 대한 GitHub 이슈 생성간단하지만 꽤나 강력하고 쓸모가 있었다. Vue.js 및 한국어 외 다른 언어를 대상으로 하는 Vite 번역 프로젝트에서도 사용중이어서, 신뢰도도 낮지 않았다. 그렇게 Ryu-Cho를 2년 가까이 사용했고, 아쉬운 부분이 눈에 보였다.## Ryu-Cho 문제점다음과 같은 문제점을 느꼈다:- **릴리스 상태 추적 자동화 불가능** - 번역 전 릴리즈 여부를 확인해야 하는 번거로움이 그대로 남아있음 - 릴리스되지 않은 기능의 문서를 번역하는 경우 발생 - 이를 일일이 추적한다면 수동 관리와 큰 차이가 없음- **이슈 관리의 한계** - 이슈 라벨링 기능 부재로 번역 이슈와 일반 이슈가 섞임 - 작업 상태 추적이 어려워짐- **설정과 유지보수의 어려움** - 문제 발생 시 디버깅을 위한 로그 부족 - 설정 옵션의 유연성 부족새로운 도구의 필요성을 느꼈다. 그렇게 Yuki-no를 개발했다.# Yuki-no

Yuki-no 스크립트 실행 모습 / GitHub

Ryu-Cho 한계를 극복하기 위해 개발된 [Yuki-no](https://github.com/Gumball12/yuki-no/)는 현재 [Vite 한국어 문서 번역 프로젝트](https://github.com/vitejs/docs-ko), [Vue 한국어 문서 번역 프로젝트](https://github.com/vuejs-translations/docs-ko), 그리고 [Vite 번역 템플릿](https://github.com/tony19/vite-docs-template)에서 실제로 사용중이다.## 주요 이점![Yuki-no 도입](/images/250214/with-ryu-cho.png) _Yuki-no 동작 방식_1. **자동화된 변경 사항 추적** ![Automated Change Tracking](/images/250214/automated-change-tracking.webp) _Yuki-no로 생성된 [Vite 한국어 번역 프로젝트 이슈 목록](https://github.com/vitejs/docs-ko/issues?q=is%3Aissue%20label%3Async) 중 일부_ - 원본 저장소 내 필요한 부분에 대한 변경 사항만을 모니터링 - 번역이 필요한 부분을 GitHub 이슈로 생성 및 라벨링2. **릴리스 상태 기반 번역 관리** ![Automated Release Tracking](/images/250214/automated-release-tracking.webp =450x) _Yuki-no로 관리되는 [릴리스 코멘트 및 라벨](https://github.com/vitejs/docs-ko/issues/1126)_ - 정식 릴리스된 내용과 프리 릴리스 버전 구분 - 릴리스 상태에 따른 라벨링 - 불필요한 번역 작업 방지3. **효율적인 작업 관리** - 번역이 필요한 부분만 한눈에 파악 가능 - GitHub 기반 이슈 관리 프로세스 그대로 사용 가능 - Octokit 플러그인([retry](https://github.com/octokit/plugin-retry.js), [throttling](https://github.com/octokit/plugin-throttling.js/)) 을 이용해 효율적인 GitHub API 사용# Yuki-no 사용하기아래 내용은 [리드미](https://github.com/Gumball12/yuki-no/blob/main/README.md#usage)에서도 확인할 수 있다. 만약 Ryu-Cho 또는 이와 유사한 방식으로 번역 프로세스가 구성되어 있다면 [마이그레이션 문서](https://github.com/Gumball12/yuki-no/blob/main/MIGRATION.md)를 참고하자.## 1. GitHub Actions 설정먼저 저장소에 GitHub Actions 권한을 설정해야 한다. 이는 Actions에서 Issues 및 Issue Comments를 생성하기 위해 필요하다. 참고로 Ryu-Cho와 같은 GitHub Issues 기반 번역 프로세스를 구축하는 모든 Actions에서 이를 요구한다:![settings](/images/250214/settings.webp) _GitHub Actions 권한 설정을 해주지 않으면 에러가 발생한다_- 리포지토리 Settings 탭으로 이동 > Actions > General > Workflow permissions 항목- "Read and write permissions" 선택- 변경 사항 저장## 2. Yuki-no 설정 파일 작성다음으로 `.github/workflows/yuki-no.yml` 파일을 생성해야 한다. 자세한 내용은 [Yuki-no 문서](https://github.com/Gumball12/yuki-no/blob/main/README.md#configuration)를 참고하자. 가령 Vite 번역 프로젝트를 시작한다고 했을 때, 아래와 같이 구성할 수 있다:```yml# .github/workflows/yuki-no.ymlname: yuki-noon: schedule: - cron: '0 * * * *' # 매시간 실행 workflow_dispatch: # 수동 실행 옵션jobs: yuki-no: runs-on: ubuntu-latest steps: - uses: Gumball12/yuki-no@v1 with: access-token: ${{ secrets.GITHUB_TOKEN }} head-repo: https://github.com/vitejs/vite.git track-from: abcd1234 # 추적을 시작할 커밋 해시 include: | docs/** release-tracking: true```## 3. 번역 프로젝트 시작하기이제 번역 작업은 이렇게 진행하면 된다:1. **자동 이슈 생성** - `track-from` 다음 커밋부터 시작해, 원본 문서가 업데이트되면 자동으로 이슈 생성 - 릴리스 상태도 자동으로 추적 - 커밋에 대한 정보 포함2. **작업 현황 관리** - 라벨로 작업 상태 관리 (예: 번역 이슈는 `sync`이 붙음) - 릴리스 추적 라벨로 우선순위 파악 (예: 정식 릴리스되지 않은 변경 사항에는 `pending`이 붙음) - 작업자 배정 및 진행 상황 추적3. **번역 및 리뷰** - PR 생성 및 리뷰 진행 - 릴리스 상태에 따른 번역 및 배포 시점 조절## 효율적인 관리를 위한 팁1. **파일 패턴 활용** ```yml include: | docs/**/*.md # 문서 파일만 추적 .vitepress/config.ts # 설정 파일도 포함 exclude: | docs/**/*.test.ts # 테스트 파일 제외 docs/internal/** # 내부 문서 제외 ``` - `include`로 번역이 필요한 파일만 선택적으로 추적 - `exclude`로 불필요한 파일 제외 - [Glob 패턴](https://github.com/micromatch/picomatch?tab=readme-ov-file#advanced-globbing)을 사용해 유연한 파일 선택 가능2. **릴리스 추적 시스템 활용** ```yml release-tracking: true release-tracking-labels: | pending pre-release released ``` - `release-tracking`: 릴리스 상태 자동 추적 활성화 - `release-tracking-labels`: 릴리스 상태별 라벨 지정 - 라벨 및 이슈 코멘트를 통한 릴리스 상태 확인 **동작 방식:** - 새 커밋이 감지되면 `sync` 라벨로 시작 (`labels` 옵션을 통해 지정, 기본값 `sync`) - 정식 릴리스 이전 변경 사항은 `pending` 라벨이 붙음 (`release-tracking-labels` 옵션을 통해 지정, 기본값 `pending`) - 릴리스 상태 변경 시 이슈에 코멘트 자동 추가 - 정식 릴리스 시 `pending` 라벨 제거됨# 마무리Yuki-no를 도입한 후, Vite 한국어 문서 번역 프로젝트는 이런 개선을 이루었다.- 불필요한 번역 작업을 피할 수 있게 됨- 번역 작업 만족도 향상- 번역 진행 방식 간결화 및 진입 장벽 낮춤현재 Vite 한국어 문서 번역 프로젝트는 Yuki-no를 통해 안정적이고 효율적인 번역 프로세스를 운영하고 있으며, 이는 다른 번역 프로젝트에도 좋은 참고 사례가 될 수 있을 것이라 생각한다.더 자세한 내용은 [Yuki-no 문서](https://github.com/Gumball12/yuki-no)를 참고하자. 질문이나 제안이 있다면 [GitHub Issues](https://github.com/Gumball12/yuki-no/issues)에 남겨주기를 바란다.

Cursor와 함께한 Vite 문서 번역 이야기

shj — Fri, 10 Jan 2025 00:00:00 GMT

# Cursor와 함께한 Vite 문서 번역 이야기![번역 완료](/images/250110/trans-comp.webp) _Cursor로 번역한 결과_오픈소스 번역은 누구나 시작할 수 있는 기여 활동이다. 하지만 꾸준한 관리는 조금 다른 이야기다. 특히 [Vite](https://vite.dev)처럼 빠르게 발전하는 프로젝트 문서는 더욱 그렇다. 새로운 기능이 추가되고 API가 변경될 때마다 문서도 함께 업데이트해야 하니까.최근 [Vite 6.0](https://vite.dev/blog/announcing-vite6) 릴리스로 한글 번역이 필요한 문서가 무려 27개나 쌓였다. 평소 3배가 넘는 분량이었다. 내용도 만만치 않았다. 빌드 시스템과 프런트엔드 생태계에 대한 깊은 이해가 필요했다. 하지만 놀랍게도 [Cursor](https://cursor.com)라는 AI 도구 도움으로 3일 만에 모든 번역을 완료했다.참고로 나는 프롬프트 엔지니어링을 전문적으로 배우거나, AI를 깊이 있게 다루는 사람이 아니다. 오히려 한동안 [GitHub Copilot](https://github.com/features/copilot)같은 AI 코딩 도구를 멀리하기도 했다. 그런데 어떻게 이런 성과를 낼 수 있었을까? Cursor(정확히는 [Claude](https://www.anthropic.com/claude)) 도움을 받으면 생각보다 어렵지 않다. 여기서는 AI 도움을 받아 효율적으로 번역한 경험을 공유하려 한다.# CursorVite 문서 번역은 내가 꾸준히 참여하는 오픈소스 활동 중 하나다. 양이 그렇게 많지는 않아서 보통 2주에 한 번 정도 [ChatGPT](https://chat.openai.com)와 [DeepL](https://www.deepl.com)을 활용해 번역하는데, 이번에는 상황이 달랐다. Vite 6 릴리스와 함께 27개나 되는 새로운 문서가 추가됐다. 게다가 내용을 살펴보니 빌드 환경(Environment) 등 기술적으로 깊이 있는 내용이 많았다. 부담스러워서 일주일 정도 미뤄버렸고, 아무 진전도 없었다.한동안 멀리했던 GitHub Copilot을 다시 써볼까 고민했다. 월 10달러로 Cursor보다 저렴하지만, 내가 필요한 건 단순 코드 자동완성이 아닌 여러 파일을 동시에 수정하고 문맥을 이해하는 도구였다. 그러던 중 Cursor를 알게 됐다.![Cursor](/images/250110/cursor.webp) _Cursor - The AI Code Editor_[Cursor](https://cursor.sh)는 샌프란시스코 AI 스타트업이 개발한 AI 코딩 어시스턴트다. 여러 파일을 AI가 직접 수정할 수 있고, 코드베이스 전체를 이해하며 제안한다는 점이 매력적이었다. 특히 번역할 때는 기존 번역을 참고해 일관된 톤과 용어를 유지해야 하는데, Cursor는 이런 니즈를 완벽하게 충족시켜 줬다. 결과적으로 27개 문서를 단 3일 만에 번역하고 검수까지 마쳤다.# 진행 방식Cursor 최고 장점은 여러 파일을 동시에 수정할 수 있다는 점이다. [Composer](https://docs.cursor.com/composer/overview)(Agent) 기능을 활용하면 여러 파일 또는 디렉터리 단위로 번역을 진행하면서, 번역 내용에 대한 질문이나 피드백도 주고받을 수 있다. 현재 작업과 직접 관련 없는 프롬프트 생성 같은 요청은 Chat 기능을 활용했다.작업 흐름은 다음과 같았다:1. **번역 규칙 설정**: 먼저 Chat으로 Cursor가 일관된 규칙을 따르도록 프롬프트를 만들어달라 요청했다. 기존에 내가 사용하던 번역 규칙을 전달했고, 프롬프트 초안을 다듬어 최종 버전을 완성했다.![프롬프트 생성 요청](/images/250110/gen-prompt.webp) _프롬프트 생성 요청_

열어서 프롬프트 보기

```md# 번역 가이드라인당신은 영어로 된 Vite 문서를 한글로 번역하는 전문 번역가입니다. 아래 규칙을 따라 문서를 번역해주세요.1. **문장 구성 원칙** - 불필요한 조사와 중복 표현 제거 - 자연스럽고 간결한 문장 구성 - 문장 간 연결성을 위한 적절한 접속사 사용 - 원본 내용은 생략하지 않음2. **기술 용어 처리** - 일관성 있는 기술 용어 사용 - 직역을 피하고 문맥에 맞는 적절한 표현 사용 - "import" → "의존성" 또는 "모듈을 가져다 쓰는" 등 - "resolve", "evaluation" 등도 문맥에 맞게 번역 - 용어 변경 시 원본 표현을 답변에 포함 - @TERMINOLOGY.md 파일 참고3. **코드 관련 규칙** - 코드 예제는 주석만 번역 - twoslash 주석 고려하여 실제 주석만 번역 - 코드 자체는 수정하지 않음4. **문서 구조** - 원본 문서의 라인 단위 구조 유지 - 마크다운 heading에 앵커 지정 필수 - 형식: `{#slugified-heading}` - 예시: "## HMR `hotUpdate` plugin hook" -> "## HMR `hotUpdate` 플러그인 훅 {#hmr-hotupdate-plugin-hook}" - 예시: "## `myExportedAPI`" -> "## `myExportedAPI` {#myexportedapi}"5. **품질 관리** - 번역 전 정보의 정확성 확인 - 레퍼런스 정보 포함 - 기존 코드베이스의 어투 유지 - 한국어 독자가 이해하기 쉽게 표현 - 항상 한국어 맞춤법을 따라야 함6. **작업 방식** - 파일 단위로 번역 진행 - 번역 결과는 답변하지 말고, "요청한 파일을 반드시 수정해서 직접 적용" - 요청 문서 중 한국어로 대부분 번역된 문서가 있을 수 있으며, 그럼에도 파일 내용을 꼼꼼히 확인해 한국어 번역이 필요한 부분을 찾아야 함 - 이미 번역이 되어있더라도 단 한 줄도 생략하지 않고 한줄씩 처음부터 끝까지, 하나 하나 꼼꼼히 확인 - 파일 크기가 크더라도 중간에 멈춰서 계속 진행할지 물어보지 말고 끝까지 진행```

이 프롬프트는 [Cursor Notepad](https://docs.cursor.com/features/beta/notepads)에 저장해두고, 번역을 요청할 때마다 참조했다.2. **파일 또는 디렉터리 단위로 번역 요청**: Composer로 파일이나 디렉터리 단위 번역을 요청한다. 이때 앞서 만든 프롬프트를 참조해 기존 번역과 일관된 톤과 용어를 유지했다.![파일 번역 요청](/images/250110/trans-a-file.mp4 t=0.01)모든 파일에 대해 번역을 요청할 수는 있지만, 나는 보통 파일 단위로 작게 나눠서 요청한다. 검수 과정에서 이해가 안 되는 부분이 있을 때 질문하거나, 수정을 요청하기가 더 수월하기 때문이다. 또한 너무 큰 단위로 번역을 요청하면 AI가 내용을 생략하거나 예상치 못한 파일을 생성하는 경우가 있어서, 작은 단위로 나누는 편이 여러 방면에서 더 효율적이었다.![비동기적으로 작업](/images/250110/process-with-trans.mp4 t=0.01)Cursor에 익숙해진 후에는 여러 파일을 동시에 작업하며 번역과 검수를 병행했다. 이렇게 작업 효율을 더욱 높일 수 있었다.3. **검수 및 번역 피드백을 통한 개선**: AI 번역은 완벽하지 않다. 문서 신뢰도와 품질을 위해 모든 내용을 꼼꼼히 검토하고, 이해가 안 되는 부분은 반드시 확인해야 한다. 이전에는 이 과정에서 많은 시간이 걸렸는데, Cursor가 큰 도움이 됐다.![번역 개선 요청](/images/250110/revise.mp4 t=0.01)예를 들어 "Target"이라는 단어는 문맥에 따라 다르게 번역해야 한다. 단순히 "대상"으로만 번역하면 의미가 모호해진다. 특히 Vite 6에서 새로 도입된 Environment API 관련 문서는 더 까다로웠다. 빌드 환경과 관련된 복잡한 개념을 다루고 있어서 이해하기 어려웠는데, Cursor는 문맥을 파악해 적절한 번역을 제안하고 관련 문서까지 찾아줘 큰 도움이 됐다. 물론 AI가 기술적 맥락을 잘못 이해한 경우도 있어서 이는 바로잡아야 했지만, 대부분 정확한 방향을 제시해줬다.이후 다음 번역 대상으로 넘어가 2번 과정부터 반복했다.# 유의 사항1. **질문과 피드백을 모아서 요청하기**: 기본적으로 Cursor는 월 500 크레딧을 제공한다. 많아 보일 수 있지만, 무분별하게 사용하면 금방 소진된다. 질문과 피드백을 모아서 한 번에 요청하면 크레딧을 더 효율적으로 사용할 수 있다.2. **정확한 컨텍스트 제공하기**: 이미 번역된 문서 중에서 새로 추가된 문장을 번역할 때, AI가 이를 놓치고 넘어가는 경우가 있었다. 이런 경우에는 해당 부분을 명확하게 지정해서 컨텍스트로 전달해야 한다.# 마치며이러한 과정을 거쳐 27개 파일, 약 500줄에 달하는 문서를 3일 만에 번역하고 검수했다. 130개 크레딧(약 $5.2)을 사용했지만, 투자 대비 효율이 매우 높았다. 하지만 단순히 속도가 빨라진 점보다 더 중요한 건, 번역에 대한 심리적 부담이 크게 줄었다는 점이다.최근 [GeekNews에서 본 글](https://news.hada.io/topic?id=18506)처럼, 기술 문서 번역은 여전히 많은 과제를 안고 있다. 특히 "새로 업데이트되는 문서가 많으나, 커뮤니티 관심이 적다보니 빠른 반영이 어렵다"는 지적이 가슴에 와닿았다. AI가 이러한 간극을 메우는 데 도움이 될 수 있지 않을까?[Vite 한글 문서](https://ko.vitejs.dev)는 아직 발전 여지가 많다. 커뮤니티 논의도 적고, 놓친 부분도 많다. 하지만 이번 경험으로 AI 기반 번역 워크플로우 가능성을 확인했다. 앞으로 이 경험을 바탕으로 더 체계적인 번역 프로세스를 만들고, 다른 오픈소스 번역 커뮤니티에도 기여하고 싶다. 기술 문서 번역 진입 장벽을 낮추고, 더 많은 한국 개발자가 최신 기술 문서를 쉽게 접할 수 있길 바라며.

미국에서 만난 사용자 중심 개발

shj — Sun, 24 Nov 2024 00:00:00 GMT

![공항 사진](/images/241104/airport.webp) _인천국제공항 어느 창문 앞_> 이제 한국 땅을 벗어나는구나. 어떤 경험을 마주할까. 돌아오면 어떤 마음을 갖게 될까. 달리(고양이)는 괜찮을까. 미국까지 갔는데 프로젝트가 망하면 어떡하지.2024년 9월 20일. 눈오는 겨울 새벽 밤 계획에 없던 외출을 할 때처럼 두근거리는 마음을 품고 나는 공항으로 향했다. 그 곳에는 함께 출발하는 글로벌 부트스트랩 팀 동료들이 나를 기다리고 있었다.# 작은 스타트업처럼 일하기우리 회사는 AI 음성 합성(TTS, Text-to-Speech) 기반 콘텐츠 제작 도구를 개발한다. 더빙, 영상 편집, 목소리 복제 등 다양한 기능을 제공하고 있는데, 핵심은 AI TTS 에디터다. 이 에디터는 국내 크리에이터들에게 이미 호평을 받았지만, 해외 시장에서는 아쉬운 부분이 많았다. 이러한 상황을 타파하고자 했다."이번에는 정말 다르게 해봐야 해요."처음 출장을 논의할 때 대표가 했던 말이다. 우리 제품은 이제 글로벌 시장에서 경쟁해야 했고, 기존 TTS 에디터는 사용성에 문제가 있었다. 지금까지 접근 방식으로는 살아남기 어려울 것이다. 하지만 무엇이 문제인지는 감을 잡기 어려웠다.그래서 미국 캘리포니아 San Mateo에 있는 미국 지사로 향했다. 목표는 단순했다. 마치 초기 스타트업처럼 빠르게 움직이며, 실제 영어권 사용자 피드백을 바탕으로 제품을 개선하는 것. 그렇게 총 6명으로 된 글로벌 부트스트랩 팀이 만들어졌다(한국: 개발자 3명 + 디자이너 1명, 현지: 대표 + PM).![Concar 400 Dr에 있는 WeWork 오피스](/images/241104/concar-office.webp) _Concar 400 Dr에 있는 WeWork 오피스__"한국에서 수백 번 회의하기보다, 현지에서 직접 사용자를 만나는 30분이 더 가치 있다."_첫날 미팅에서 나온 이 말은 남은 여정을 관통하는 키워드가 되었다.## 데일리 프로토타입과 인터뷰 사이클우리는 3주 동안 16번 프로토타입을 만들었고, 이를 바탕으로 사용자 인터뷰를 진행했다. 일정은 대략 이런 흐름이었다:1. 오전: 사용자 인터뷰 진행2. 오후: 인터뷰 결과 분석 및 토론 (평균 2~3시간)3. 저녁~밤: 다음 날 인터뷰를 위한 프로토타입 개발4. 다음 날 아침: 마지막 테스트 및 디버깅 후 다시 인터뷰마치 정밀한 기계처럼 돌아가는 이 사이클이 처음에는 버거웠다. 개발자인 나는 코드를 깔끔하게 작성하고 싶었고, 버그 없이 완벽한 프로토타입을 만들고 싶었다. 하지만 동료가 해준 말을 듣고 생각이 달라졌다._"완벽한 코드보다 사용자 반응을 빨리 보는게 중요해요. 무엇이 시장에서 성공하는지부터 알아야 합니다. 지금은 스피드가 생명입니다."_그리고 이내 이 방식이 얼마나 강력한지 경험하게 되었다. 우리는 2~3일에 한 번씩 실제 사용자에 대한 반응을 볼 수 있었고, 그 때마다 제품은 시장이 요구하는 방향으로 발전했다.![프로토타입 중 일부](/images/241104/the-prototype.webp) _프로토타입 중 일부_특히 사용자가 프로토타입을 사용하다가 당혹스러운 표정을 짓는 순간이 기억에 남았다. 개발자인 내가 당연하게 생각했던 UX 패턴이 사용자에겐 전혀 직관적이지 않았다. 이런 순간들이 쌓이면서 "공급자 관점"과 "사용자 관점"이 얼마나 다른지 피부로 느낄 수 있었다.# 인사이트: 시장에서 선택받기 위한 조건## 1. 사용자와 거리를 좁혀야 한다미국 출장에서 얻은 가장 큰 인사이트는 "공급자 생각"과 "사용자(시장)가 원하는 것" 사이 간극이 생각보다 훨씬 크다는 사실이었다.한 가지 예를 들어보자. 우리는 TTS 에디터에 음성, 캐릭터, 배경 등 다양한 편집 기능을 담았었는데, 이는 "더 많은 기능"이 "더 좋은 제품"이라 생각해서였다. 그러나 대다수 사용자들은 텍스트를 잘 편집할 수 있고 재생 버튼을 눌렀을 때 음성이 "잘" 흘러나오면 충분히 만족했다."왜 이 기능이 필요한가요?" "제가 원하는 기능을 찾을 수 없어요."이 질문은 마치 우리가 만든 프로덕트가 쓸모없고, 실패했다고 말하는 것처럼 들렸다. 하지만 실제로는 그렇지 않았다. 그저 방향이 달랐을 뿐이다. 사용자가 무엇을 요구하는지 다시 생각하게 만들었고, 불필요한 복잡성을 제거하는 데 큰 도움이 되었다.> "왜(Why)"라는 질문은 기획, 디자인, 개발 모든 단계에서 가장 중요하다.매일같이 사용자를 만났고, 회의에서는 이 "왜"에 집중했다. 왜 그런 행동을 했는지, 왜 그런 표정을 지었는지, 왜 다른 버튼을 찾았는지. 이런 질문들이 방향을 잡아주는 나침반이 되었다. 모두 머리 속 상상이 아닌, 실제 사용자를 만나기 전까지는 알지 못했었다.## 2. 의사결정 구조: 대표는 실무와 가깝게지금 근무중인 회사는 한국과 미국 지사가 있고, 대표는 미국 지사에서 글로벌 대상으로 세일즈, 미팅, 인터뷰 등을 수행하고 있었다. 한국에 있던 나는 출장 전 '대표와 함께 있으면 일할 때 좀 어렵지 않을까' 하는 생각이 있었는데, 오산이었다. 현장에서 경험해보니 여러 이점이 있었다:1. **의사결정 속도**: "이 기능 넣어볼까요?" 라는 질문에 대한 답변이 상호 즉각적으로 이루어진다.2. **컨텍스트 공유**: 대표와 함께 직접 사용자 반응을 보면서, 모두 같은 경험을 공유할 수 있다.3. **방향성 정렬**: 대표가 생각하는 비전과 팀이 관찰한 결과가 자연스럽게 조율된다."이거 정말 좋은데요! 다음 버전에서는 이렇게 해봅시다."대표가 직접 테스트하고 즉석에서 피드백을 주는 모습은 마치 초기 스타트업에서 창업자가 제품을 손수 다듬는 모습과 같았다. 빠르고, 즉각적이었으며, 결정에 힘이 실렸다.> 회사가 커지더라도 의사결정권자는 현장과 멀어지면 안 된다.이번 경험은 회사 규모와 관계없이, 핵심 결정권자가 사용자와 가까이 있어야 한다는 교훈을 주었다. 특히 글로벌과 경쟁하며 빠르게 움직여야 하는 상황에서는 이런 구조가 훨씬 효과적이라 생각한다.## 3. 빠른 검증 사이클: 논의보다 프로토타입출장 전에는 기획과 디자인을 꼼꼼히 검토하며 많은 논의를 거친 후에야 개발을 시작했다. 하지만 미국에서는 거의 반대로 일했다."이게 좋을 것 같아요. 일단 가장 빠르고 쉽게 만들어 보고 반응을 지켜봅시다."긴 논의로 모든 상황을 예측하려고 노력하는 대신, 빠르게 프로토타입을 만들고 실제 사용자 반응을 확인하는 방식이다. 이런 접근 방식은 처음에는 무모해 보였지만, 실제로는 놀라울 정도로 효율적이었다. 그리고 순서가 뒤로 이동하기는 했지만, 오히려 더 깊이 있는 논의가 이루어졌다:1. 간략한 아이디어 미팅 (30분~1시간)2. 프로토타입 개발 (3~4시간)3. 사용자 테스트4. 결과를 바탕으로 한 심층 논의 (2~3시간)이러한 방식이 갖는 장점은 실제 데이터를 기반으로 논의가 이루어진다는 점이다. "이 버튼을 여기에 놓으면 어떨까요?"라는 추상적인 질문 대신, "어제 인터뷰를 진행했던 사용자 중 n%가 이 버튼을 찾지 못했습니다. 이는 우리 예상치보다 낮으니 개선해야 합니다."와 같은 구체적인 사실과 숫자를 바탕으로 대화할 수 있었다.> 불확실성이 높을수록 빠른 검증이 중요하다.특히 새로운 시장이나 기능을 개발할 때는 아무리 경험 많은 전문가라도 모두 예측하기는 어렵다. 이런 상황에서는 빠르게 만들고 검증하는 사이클이 훨씬 효과적이다.# 개인적인 성장![해밀턴 산](/images/241104/hamilton-mountain.webp) _Apple Park 뒤로 보이는 해밀턴 산_스스로도 많은 성장을 했다고 생각한다. 새로운 기술을 빠르게 학습하고 적용하는 방법, 팀원들과 효율적으로 소통하는 방법, 그리고 무엇보다 사용자 중심으로 생각하는 방법을 배웠다.## 기술 학습새로운 기술을 접할 때 가장 효과적이었던 방법은 다음과 같다:1. 공식 문서나 신뢰할 수 있는 예제 코드를 먼저 살펴본다2. 핵심 개념이나 패턴을 파악한다3. 실제 필요한 부분에 바로 적용해본다4. 문제가 발생하면 다시 문서로 돌아가 깊이 있게 이해한다이 과정을 반복해 Slate.js도 짧은 시간 내에 파악해 프로토타입에 적용할 수 있었다.## 효율적인 소통 방식빠른 개발 사이클에서 발견한 효과적인 소통 방식은 다음과 같다:1. 짧고 명확한 미팅 (5~10분)2. 논의 사항을 미리 정리3. 결과와 다음 할 일을 문서화특히 컨텍스트 스위칭이 많은 상황에서는 짧게 자주 소통하는 방식이 더 효과적이었다.## 돌아온 후출장을 마치고 한국으로 돌아온 후, 우리 팀이 일하는 방식에는 적지 않은 변화가 생겼다:1. **프로토타입 중심 개발**: 긴 논의보다는 빠른 검증과 실제 데이터를 우선한다2. **사용자 중심 사고**: 모든 기능에 "왜?"라는 질문을 먼저 던진다또한 출장 중 개발한 프로토타입이 실제 제품 로드맵에 반영되어 개발이 진행되고 있다는 점은 큰 성취감을 주었다.# 마치며![떠나는 길](/images/241104/flight.webp) _떠나는 길 비행기 안에서_'그래, 다녀오면 무언가 얻어오겠지'라는 막연한 생각으로 비행기에 올랐다. 그런데 예상보다 훨씬 많은 배움을 얻었다. 가장 중요한 교휸은 "사용자(시장)와 가까이 있어야 한다"는 점이다. 뛰어난 개발자도 상상 속에서는 좋은 제품을 만들 수 없다. 그렇게 시장에서 검증되면 그 방향으로 "빠르게 움직이고, 자주 검증"해야 한다. 글로벌 시장 진출도 필수적이다.이 접근 방식은 실제 성과로 이어졌다. 프로토타입 기반 제품 릴리스 후 1주일 만에 이런 성과를 얻었다:- 총 사용자 수 51.2% 증가 (4,535명 -> 6,859명)- 신규 참여 사용자 46.3% 증가 (2,508명 -> 3,668명)- 신규 사용자에 대한 가입 전환율 71.4% 향상 (18.9% -> 32.4%)- 활성 로그인 사용자 수 136.9% 증가 (549명 -> 1,301명)- 사용자 활성 비율 57.0% 증가 (12.1% -> 19.0%)이는 우리가 선택한 방향이 시장에서 어느정도 검증되었음을 의미한다. 특히 영어권에서 높은 반응을 보여 글로벌 시장에서 가능성을 보여주었다.이 경험을 바탕으로 더 나은 제품을 위한 도전을 계속하고 싶다. 다음에 이런 기회가 한번 더 생긴다면 이번에 배웠던 내용을 바탕으로 더 큰 성과를 내보고 싶다.> "The best way to predict the future is to create it." - Abraham Lincoln우리가 만드는 제품이 미래를 만들어가는 작은 조각이 되길 바라며 글을 마친다.

웹에서 비디오와 음성을 동기화하는 방법

shj — Thu, 03 Oct 2024 00:00:00 GMT

# TL;DR- `HTMLMediaElement` 이벤트 중 `canplay`, `waiting`, `loadstart`를 이용해 버퍼링 상태 감지가 가능하다.- 모든 미디어 요소가 재생 준비될 때까지 재생을 지연시켜 동기화가 가능하다.- [이 링크](https://codepen.io/Gumball12/pen/EaxdqOV?editors=1010)에서 Chrome DevTools와 네트워크 시뮬레이션을 이용해 실제 동작을 테스트할 수 있다.# 들어가며웹 애플리케이션에서 여러 미디어 요소를 동시에 재생하기는 조금 까다롭다. 그냥 `video.play()`와 `audio.play()`를 같이 호출하는 것으로는 부족하다. 네트워크 상황이나 리소스 크기에 따라 각 요소가 다른 시점에 준비되기 때문이다. 이 글에서는 [`HTMLMediaElement` 이벤트](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#events)로 여러 미디어를 함께 재생하는 방법을 소개한다. 말 그대로 모든 요소가 준비될 때까지 기다렸다가 동시에 재생하는 방식이다.# 미디어 동기화미디어 재생 시점은 네트워크 상태, 리소스 크기, 디바이스 성능 등 다양한 요인에 영향받는다. 이런 이유로 여러 미디어 요소를 동시에 재생하게 되면 각기 다른 타이밍에 버퍼링되어 동기화가 깨지는 상황이 발생하기도 한다. 특히 네트워크가 안정적이지 않은 모바일 환경에서 이러한 현상이 더욱 두드러진다.## 버퍼링 이벤트`HTMLMediaElement`는 미디어 상태 파악을 위한 몇 가지 이벤트를 제공한다. 이 중 버퍼링과 관련된 이벤트를 살펴보면 다음과 같다:```tsconst BUFFERING_EVENT_NAME_LIST = [ 'canplay', // 재생할 수 있을 정도로 데이터가 로드됨 'waiting', // 재생하려면 더 많은 데이터 로드가 필요함 'loadstart', // 미디어 로드 시작됨];```앞서 말했듯 동기화 핵심 아이디어는 간단하다. 모든 미디어 요소가 준비될 때까지 재생을 지연시키면 된다. 구현 방법을 단계별로 살펴보자.## 동기화 구현### 1. 컨트롤러 인터페이스 정의먼저 미디어 요소를 전반적으로 재생/일시정지하는 컨트롤러가 필요하다. 다음은 이해를 돕기 위한 인터페이스 예시이다:```tsinterface Controller { isPlay: boolean; play(): void; pause(): void;}```### 2. 버퍼링 감지이제 버퍼링을 감지하는 로직을 구현해보자.```ts// 버퍼링 중인 미디어 요소 추적let buffered: HTMLMediaElement[] = [];let bufferCheckIntervalId = -1;// 중복 핸들링 방지const bufferingSymbol = Symbol('withBuffering');const withBuffering = (controller: Controller, mediaContainer: HTMLElement) => { const alreadyHandled = mediaContainer[bufferingSymbol]; if (alreadyHandled) { return; } mediaContainer[bufferingSymbol] = true; // 컨테이너 내 모든 미디어 요소에 대해 이벤트 등록 BUFFERING_EVENT_NAME_LIST.forEach(evtName => mediaContainer.addEventListener( evtName, ({ target }) => isMediaElement(target) && tryBuffering(controller, target), { capture: true }, ), );};```이 코드는 미디어 컨테이너 내 모든 미디어 요소에 대해 앞서 언급했던 버퍼링 관련 이벤트 핸들러를 등록한다. 유의해야 할 사항은 `capture: true` 옵션으로 이벤트 캡처 단계에서 핸들링해야 한다는 점인데, `canplay`와 `waiting` 이벤트는 버블링되지 않기 떄문이다[^1].[^1]: MDN 문서([canplay](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/canplay_event), [waiting](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/waiting_event))를 보면 "This event is not cancelable and does not bubble." 라고 언급된다.### 3. 버퍼링 처리```tsconst tryBuffering = ( controller: Controller, mediaElement: HTMLMediaElement,) => { const noNeedBuffering = !controller.isPlay || isMediaPlayable(mediaElement) || buffered.includes(mediaElement); if (noNeedBuffering) { return; } const preventPlay = () => controller.pause(); preventPlay(); mediaElement.addEventListener('playing', preventPlay); buffered.push(mediaElement); startCheckMediaIsPlayable(() => { clearBuffer(preventPlay); controller.play(); });};const clearBuffer = (preventPlay: () => void) => { window.clearTimeout(bufferCheckIntervalId); bufferCheckIntervalId = -1; buffered.forEach(element => element.removeEventListener('playing', preventPlay), ); buffered = [];};````tryBuffering` 함수는 버퍼링이 필요하면 모든 재생을 멈추고(`preventPlay`) 모든 미디어 요소가 준비될 때까지 대기하는 동작을 한다.`clearBuffer`는 말 그대로 버퍼링 완료 시점에 리소스를 정리하는 함수이다.### 4. 재생 가능 상태 확인```tsconst CHECK_INTERVAL_MS = 3000; // 3000ms마다 미디어 상태를 확인const startCheckMediaIsPlayable = (onPlayable: () => void) => { // 중복 체크 방지 if (bufferCheckIntervalId !== -1) { return; } const executeOnPlayableWhenEveryPlayable = () => { const everyPlayable = buffered.every(isMediaPlayable); if (everyPlayable) { onPlayable(); return; } bufferCheckIntervalId = setTimeout( executeOnPlayableWhenEveryPlayable, CHECK_INTERVAL_MS, ); }; executeOnPlayableWhenEveryPlayable();};```이 함수는 모든 미디어 요소가 재생 가능한지 지속적으로 확인하는 동작을 수행한다.### 5. 재생 가능 여부 판단 및 버퍼 초기화```tsconst isMediaPlayable = (mediaElement: HTMLMediaElement) => { if (mediaElement.networkState !== mediaElement.NETWORK_LOADING) { return true; } if (mediaElement.readyState >= mediaElement.HAVE_ENOUGH_DATA) { return true; } return false;};```이 함수는 `networkState` 및 `readyState`를 이용해 재생 가능 여부를 확인한다. 각 프로퍼티에 대한 의미를 보자면 다음과 같다.`networkState`:- `NETWORK_EMPTY` (0): 미디어 요소 최초 생성 상태, 아직 데이터가 없다- `NETWORK_IDLE` (1): 활성 네트워크 요청은 없으며, 데이터가 존재한다- `NETWORK_LOADING` (2): 브라우저가 데이터를 다운로드 중이다- `NETWORK_NO_SOURCE` (3): 미디어 리소스를 찾을 수 없다코드에서는 `!== NETWORK_LOADING`을 사용했는데, 이는 "이미 충분한 데이터가 있거나 로드가 완료되어 더 이상 로드할 데이터가 없음"을 의미한다. 즉, "재생 가능함"을 의미한다.`readyState`:- `HAVE_NOTHING` (0): 사용 가능한 정보가 없다- `HAVE_METADATA` (1): 메타데이터는 있으나, 미디어 재생을 위한 데이터는 부족하다- `HAVE_CURRENT_DATA` (2): 현재 재생 위치에 대한 데이터는 있으나, 그 이후는 충분하지 않다- `HAVE_FEATURE_DATA` (3): 현재 재생 위치와 그 다음 일부에 대한 재생 데이터가 존재한다- `HAVE_ENOUGH_DATA` (4): 버퍼링 없이 재생할 수 있을 정도로 데이터가 충분하다코드에서는 `>= HAVE_ENOUGH_DATA`를 사용했는데, 이는 "버퍼링 없이 재생 가능한 충분한 데이터가 있음"을 의미한다. 이 상태도 마찬가지로 "재생 가능함"을 의미한다.# 사용하기`withBuffering` 함수는 다음과 같이 사용할 수 있다.```html

``````tsdocument.addEventListener('DOMContentLoaded', () => { const mediaContainer = document.querySelector('.media-container'); const videoElement = document.querySelector('video'); const audioElement = document.querySelector('audio'); const controller = { isPlay: false, play() { this.isPlay = true; videoElement.play(); audioElement.play(); }, stop() { this.pause(); clearMedia(videoElement); clearMedia(audioElement); }, pause() { this.isPlay = false; videoElement.pause(); audioElement.pause(); }, }; withBuffering(controller, mediaContainer); document .querySelector('button.play') .addEventListener('click', () => controller.play()); document .querySelector('button.stop') .addEventListener('click', () => controller.stop());});const clearMedia = (mediaElement: HTMLMediaElement) => { mediaElement.currentTime = 0; const originSrc = mediaElement.src; mediaElement.src = ''; mediaElement.load(); mediaElement.src = originSrc;};```[이 링크](https://codepen.io/Gumball12/pen/EaxdqOV?editors=1010)에서 실제 동작을 테스트할 수도 있다. 접속 후 Chrome DevTools와 같은 도구를 이용해 네트워크를 3G와 같이 느린 환경으로 시뮬레이트 해보자. 모든 미디어가 충분히 버퍼링된 후 함께 재생되는 모습을 볼 수 있을 것이다.## 프로덕트 적용 시 유의점실제 환경에서는 다음 사항도 고려해야 한다:- **타임아웃:** 어떤 네트워크 환경일지 알 수 없기에, 장시간 버퍼링 시 적절하게 알려줘야 한다.- **버퍼링 시각화:** 현재 버퍼링 상태임을 적절하게 알려줘야 혼동이 없다.- **폴백(Fallback) 처리:** 잘못된 링크 등 동기화 자체가 불가능한 상황도 있다.# 맺으며웹에서 여러 미디어를 동시에 재생한다는 것은 겉보기보다 복잡하다. 그러나 이는 단순한 UX 향상을 넘어 사용자가 버퍼링으로 불편함 없이 콘텐츠를 안정적으로 경험할 수 있도록 하는 중요한 문제이다.여기서는 이벤트 기반 버퍼링 상태를 관리해 모든 미디어가 준비된 후 재생하는 방법을 이용했다. 어떤 접근법을 사용하든 무엇보다 중요한 것은 사용자 환경과 요구사항에 맞는 최적 접근법을 선택해야 한다. 웹 플랫폼은 계속 발전하고 있으며, 미디어 동기화를 위한 더 나은 API 및 툴이 앞으로도 등장할 것이라 기대한다.

iOS Safari에서 올바르게 비디오 프레임 추출하기 🔍

shj — Wed, 17 Jul 2024 00:00:00 GMT

[English](./extracting-video-frames-correctly-in-ios-safari.html)> 참고: iOS Safari 14 ~ 17.4.1 버전에서 동작을 확인했습니다.> 비디오 프레임 추출에 대한 NPM 패키지를 찾으신다면, [generate-video-dumbnail](https://npmjs.com/package/generate-video-dumbnail)은 어떠신가요? [여기서 온라인 데모를 확인해 보세요](https://gumball12.github.io/generate-video-dumbnail/).![프레임 추출 이슈](/images/240528/existing-issue.png) _iOS에서 비디오 프레임 추출은 예상과 다르게 동작하는 경우가 있습니다_최근 비디오 프레임 추출 작업을 수행했었습니다. 어렵지는 않았습니다. 약간의 추론과, ChatGPT, 그리고 구글링을 통해 빠르게 코드를 구성해 나갔습니다.```jsconst canvas = document.createElement('canvas');const ctx = canvas.getContext('2d');video.addEventListener('loadeddata', () => { canvas.width = video.videoWidth; canvas.height = video.videoHeight; ctx.drawImage(video, 0, 0, canvas.width, canvas.height); const thumbnailDataUrl = canvas.toDataURL('image/png'); document.querySelector('img').src = thumbnailDataUrl;});```그렇게 Canvas API를 이용해 완성한 코드는 macOS Safari와 Chrome 브라우저에서 예상과 같이 동작했습니다. 생각보다 일찍 끝날 것 같아 조금 들떠 있기도 했습니다. 그리고, iOS Safari에서 비디오 프레임을 추출해 봤는데... **아무것도 나타나지 않았습니다!** 무언가 잘못되었죠. 🤯![브라우저 스펙 테스트 실패 그래프](/images/240528/browser-failures.png) _브라우저 스펙 테스트 실패 그래프 ([데이터 소스](https://wpt.fyi/results/?label=master&label=experimental&aligned))_이와 비슷한 상황을 겪어보신 적이 있나요? iOS Safari는 매끄럽고 우아하지만, 종종 웹 프런트엔드 개발자에게 큰 고통을 주기도 합니다. 이 글에서는 **iOS Safari에서 비디오 프레임을 추출하는 방법과 그 이유** 에 대해 정리한 내용을 공유하고자 합니다. 또한 실제 기기에서 테스트할 수 있도록 온라인 데모도 함께 제공합니다.프레임 추출 문제가 얼마나 오래 지속될지는 모르겠지만, 적어도 지금은 이 가이드를 통해 의도한 대로 추출할 수 있습니다. 이 내용이 도움이 되기를 바랍니다.> [!NOTE] 들어가기 전에> 이 글은 순서가 없습니다! 위에서부터 순서대로 읽는 대신, 필요한 내용에 바로 접근해 읽을 수 있습니다. 돋보기(🔍)가 없는 제목은 각 상황을 의미합니다. 내용은 해결 방법(코드)을 먼저 보여주고, 이에 대한 이유를 그다음에 간략하게 제공합니다. 이유 앞에는 돋보기(🔍)가 있는데, 이를 클릭하면 상세한 설명을 볼 수 있습니다. 또한 iOS Safari를 대상으로만 설명합니다.# 비디오 포스터 보여주기## w/ 정적 비디오 요소```html```[CodePen](https://codepen.io/Gumball12/pen/eYaBjOK?editors=1100)- [🔍](#media-fragments-uri 'Move to Reason') `src` 애트리뷰트 마지막에 `#t=0.001`을 붙여 영상 첫 프레임을 표시할 수 있습니다.- [🔍](#preload-애트리뷰트 'Move to Reason') `preload` 애트리뷰트 값을 `metadata`로 설정할 필요는 없지만, 프레임 추출이 지연될 수 있습니다.- 비디오는 HTTP 또는 HTTPS로 제공할 수 있습니다.### 🔍 Media Fragments URIiOS Safari는 비디오 요소에 대해 **기본적으로 첫 번째 프레임을 보여주지 않습니다!** `preload="metadata"` 또는 `preload="auto"`로 설정해도 마찬가지입니다. 이 대신, [Media Fragments URI](https://www.w3.org/TR/media-frags/#introduction)를 사용해야 합니다. ([Can I Use](https://caniuse.com/media-fragments))`#t=`은 Media Fragments 요소 중 하나입니다. 이를 이용해 비디오 특정 시간을 지정할 수 있습니다(초 단위). iOS Safari에서는 이 방식을 이용해 비디오 프레임(포스터)을 보여줄 수 있습니다. 가령 `#t=0.001`로 설정한다면(0.001초), 첫 번째 비디오 프레임이 포스터로 나타납니다. 참고로 `#t=0`은 동작하지 않는다는 점을 유의하세요.### 🔍 Preload 애트리뷰트메타데이터 로드 시, [비디오 프레임 일부가 전달될 수 있습니다](https://www.w3.org/html/wiki/Elements/video#HTML_Attributes). 따라서 `preload` 속성을 `'auto'` 대신 `'metadata'`로 설정할 수 있습니다. 참고로 iOS Safari에서 `preload` 속성 기본값은 `'auto'` 이지만, 디바이스 상태에 따라(예: 배터리 절약 모드) 달라질 수 있습니다. 이러한 이유로, 속성값을 명시적으로 설정하는 것이 좋습니다.## w/ 동적 비디오 요소 (HTTP URL)```jsconst video = document.createElement('video');document.body.appendChild(video);video.preload = 'metadata';video.src = 'https://cdn.jsdelivr.net/gh/Gumball12/public-timer-mp4/timer.mp4#t=0.001';```[CodePen](https://codepen.io/Gumball12/pen/wvboxGd?editors=0110)- [🔍](#media-fragments-uri 'Move to Reason') `src` 애트리뷰트 마지막에 `#t=0.001`을 붙여 영상 첫 프레임을 표시할 수 있습니다.- [🔍](#preload-애트리뷰트 'Move to Reason') `preload` 애트리뷰트 값을 `metadata`로 설정할 필요는 없지만, 프레임 추출이 지연될 수 있습니다.- **비디오 요소는 항상 HTTPS로 제공해야 합니다.** 보안상 이유로, 동적으로 비디오 요소를 만드는 경우 `src` 애트리뷰트는 항상 HTTPS를 사용해야 합니다.## w/ 동적 비디오 요소 (Blob URL)```jsconst input = document.createElement('input');input.type = 'file';input.accept = 'video/*';document.body.appendChild(input);input.addEventListener('change', ({ target }) => { const file = target.files[0]; const url = URL.createObjectURL(file); const video = document.createElement('video'); document.body.appendChild(video); video.src = url; video.preload = 'metadata'; video.currentTime = 0.001;});```[CodePen](https://codepen.io/Gumball12/pen/eYaBjzL?editors=0110)- [🔍](#blob-url-사용-시-preload-metadata로-설정 'Move to Reason') Blob URL 사용 시, `preload`는 반드시 `'metadata'`여야 합니다. `'auto'`는 동작하지 않습니다.- [🔍](#blob-url은-media-fragments-uri를-사용할-수-없음 'Move to Reason') Media Fragments URI(`#t=`)는 Blob URL에 대해 동작하지 않습니다. 이 대신 `'loadedmetadata'` 이벤트를 이용해 `currentTime`을 `0.001`로 설정하는 방식을 이용해 주세요.### 🔍 Blob URL 사용 시 `preload='metadata'`로 설정![Preload 비교 - metadata](/images/240528/preload-metadata.png) ![Preload 비교 - auto](/images/240528/preload-auto.png) _`preload = 'metadata'`와 `preload = 'auto'` 네트워크 요청 비교_Blob URL을 사용해 비디오 요소를 생성하는 경우, **`preload`를 `'auto'`로 설정하면 지정된 시간에 대한 프레임 데이터를 가져오지 않습니다.** 실제로 네트워크 요청(위 이미지)을 확인해 보면, `preload="metadata"`는 첫 번째 프레임을 나타내기 위해 48-1541 범위만큼 데이터(Bytes)를 가져오는 것을 볼 수 있습니다. 반면 `preload="auto"`는 데이터를 가져오지 않았습니다.안타깝게도 이러한 차이에 대한 기술적인 이유는 찾지 못했습니다. 테스트는 iOS Safari 17.4.1에서 [이 코드](https://codepen.io/Gumball12/pen/PovpONw?editors=0010)를 통해 진행했습니다.### 🔍 Blob URL은 Media Fragments URI를 사용할 수 없음현재 최신 WebKit(Safari 17.4.1)에서는 **Blob URL에 Media Fragments URI(예: `#t=`)을 사용할 수 없습니다.** 관련 변경 사항은 [이 커밋](https://github.com/WebKit/WebKit/commit/7f2ea8fcf41a68add90efab89609218407e1a824#diff-015bfbdb65247b7b4cc8319b4798e660d9c6b9df998610f579376a6db3f28f24L274-L275)[^1]에서 확인할 수 있습니다. 아래는 커밋 내용 중 일부입니다:```diffBlobData* BlobRegistryImpl::getBlobDataFromURL(const URL& url, const std::optional& topOrigin) const{ ASSERT(isMainThread());- if (url.hasFragmentIdentifier())- return m_blobs.get(url.viewWithoutFragmentIdentifier());- return m_blobs.get(url.string());+ auto urlKey = url.stringWithoutFragmentIdentifier();+ auto* blobData = m_blobs.get(urlKey);+ if (m_allowedBlobURLTopOrigins && topOrigin && topOrigin != m_allowedBlobURLTopOrigins->get(urlKey)) {+ RELEASE_LOG_ERROR(Network, "BlobRegistryImpl::getBlobDataFromURL: (%p) Requested blob URL with incorrect top origin.", this);+ return nullptr;+ }+ return blobData;}```Media Fragment URI 사용 여부를 확인하는 `URL::hasFragmentIdentifier` 함수가 제거되었습니다. 대신, Media Fragment URI를 제외한 문자열을 반환하는 `URL::stringWithoutFragmentIdentifier` 함수가 사용됩니다. 따라서 Media Fragment URI 대신 `currentTime`을 사용해야 합니다.코드 히스토리도 살펴보면, 이전에는 Media Fragment URI가 Blob URL에 대해서도 지원되었음을 확인할 수 있습니다. 이는 [Safari Technology Preview 118 릴리즈 노트](https://webkit.org/blog/11439/release-notes-for-safari-technology-preview-118)와 [관련 커밋](https://github.com/WebKit/WebKit/commit/cce9f0c257eca20126d3c3d22e97e339d5718264#diff-015bfbdb65247b7b4cc8319b4798e660d9c6b9df998610f579376a6db3f28f24)에서 확인할 수 있습니다.[^1]: 이 커밋은 Blob 파티셔닝과 관련된 문제를 해결하는 것으로 보입니다. Blob 파티셔닝은 큰 데이터를 효율적으로 처리하고 사용자에게 빠른 응답을 제공하기 위해 Blob을 작은 청크로 나누는 기술입니다. 이 기능은 [Safari 17.2(19671.1.17)](https://developer.apple.com/documentation/safari-release-notes/safari-17_2-release-notes#New-Features)에서 소개되었습니다.# 비디오 프레임 하나 추출하기## w/ HTTP URL```jsconst THUMBNAIL_POSITION = 5.3;const video = document.createElement('video');video.crossOrigin = 'anonymous';video.preload = 'metadata';video.src = `https://cdn.jsdelivr.net/gh/Gumball12/public-timer-mp4/timer.mp4#t=${THUMBNAIL_POSITION}`;video.addEventListener('seeked', () => { const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); canvas.toBlob(blob => { const img = document.createElement('img'); img.src = URL.createObjectURL(blob); document.body.appendChild(img); });});```[CodePen](https://codepen.io/Gumball12/pen/qBGqyKd?editors=0110)- [🔍](#crossorigin-anonymous로-설정해-캔버스-요소에-대한-securityerror-피하기 'Move to Reason') `crossOrigin` 애트리뷰트는 `'anonymous'`로 설정해야 합니다.- [🔍](#preload-애트리뷰트 'Move to Reason') `preload` 애트리뷰트 값을 `metadata`로 설정할 필요는 없지만, 프레임 추출이 지연될 수 있습니다.- [🔍](<#비디오-프레임-데이터는-seeked-또는-timeupdate-이벤트-이후에-사용-가능-(http-url)> 'Move to Reason') 비디오 프레임 데이터는 `'seeked'` 또는 `'timeupdate'` 이벤트 이후에 사용할 수 있습니다.### 🔍 `crossOrigin='anonymous'`로 설정해 캔버스 요소에 대한 SecurityError 피하기브라우저는 기본적으로 "동일한 출처"를 가진 리소스만 허용합니다([SOP, Same Origin Policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)). 출처가 다르다면 [CORS(Cross-Origin Resource Sharing)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)를 통해 접근을 허용받아야 합니다.미디어 리소스 요청 시 [`crossOrigin` 애트리뷰트](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin)를 이용해 CORS 정책을 어떻게 처리할지 결정할 수 있습니다. 물론 아무런 설정 없이도 다른 출처(Origin)에 존재하는 미디어 리소스를 요청할 수는 있습니다. 하지만 **브라우저는 무결성이 보장되지 않는다고 간주합니다**. 그리고 이를 캔버스에 그리게 되면, **오염된(Tainted) 캔버스** 가 됩니다[^2].[^2]: 출처가 동일하다면 SOP에 의해 캔버스가 오염되지 않습니다!![오염된 캔버스](/images/240528/tainted-canvas.webp)오염된 캔버스는 웹사이트가 리소스 공유를 허용받지 못했음을 의미합니다. 이 상태에서는 픽셀 데이터에 접근할 수 없습니다. 그렇지 않으면 허용되지 않은 출처에서 이미지 내 픽셀 데이터를 임의로 유출할 수 있게 됩니다.캔버스 픽셀 데이터는 `getImageData`, `toDataURL`, `toBlob` 등으로 접근할 수 있습니다. 위에서 언급한 보안 문제를 방지하기 위해, **이러한 메서드는 오염된 캔버스에 대해 [`SecurityError`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException#securityerror)를 던집니다**. 그렇기에 `crossOrigin` 을 설정해야 합니다.옵션은 두 가지가 있습니다. 그 중 `'anonymous'`(또는 빈 문자열 `''`)는 CORS를 검증하지만, 요청에 자격 증명(쿠키, HTTP Authentication 헤더, SSL 인증서 등)을 포함하지 않도록 합니다. 이는 민감한 사용자 정보가 노출되는 상황을 방지하는 데 도움이 됩니다. 따라서 여기서는 `'anonymous'`를 사용했습니다. 다만 필요한 경우 `'use-credential'` 옵션을 통해 자격 증명을 포함할 수 있습니다.### 🔍 비디오 프레임 데이터는 `'seeked'` 또는 `'timeupdate'` 이벤트 이후 사용 가능 (HTTP URL)HTTP URL을 사용해 비디오 데이터를 요청하는 경우, 프레임 데이터는 `'seeked'` 또는 `'timeupdate'` 이벤트 이후에 접근이 가능합니다. ([⚠️ Blob URL은 다르게 동작합니다.](<#비디오-프레임-데이터는-seeked-또는-timeupdate-이후-일정-시간이-지나야-사용-가능-(blob-url)>))## w/ Blob URL```jsconst THUMBNAIL_POSITION = 5.3;const input = document.createElement('input');input.type = 'file';input.accept = 'video/*';document.body.appendChild(input);input.addEventListener('change', async ({ target }) => { const file = target.files[0]; const src = URL.createObjectURL(file); const video = document.createElement('video'); video.src = src; video.preload = 'metadata'; video.addEventListener('seeked', async () => { await new Promise(resolve => setTimeout(resolve, 100)); const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); canvas.toBlob(blob => { const img = document.createElement('img'); img.src = URL.createObjectURL(blob); document.body.appendChild(img); }); }); video.addEventListener( 'loadedmetadata', () => (video.currentTime = THUMBNAIL_POSITION), );});```[CodePen](https://codepen.io/Gumball12/pen/pomNGbb?editors=0110)- [🔍](#blob-url-사용-시-preload-metadata로-설정 'Move to Reason') Blob URL 사용 시, `preload`는 반드시 `'metadata'`여야 합니다. `'auto'`는 동작하지 않습니다.- [🔍](#blob-url은-media-fragments-uri를-사용할-수-없음 'Move to Reason') Media Fragments URI(`#t=`)는 Blob URL에 대해 동작하지 않습니다. 이 대신 `'loadedmetadata'` 이벤트를 이용해 `currentTime`을 설정해 주세요.- [🔍](<#비디오-프레임-데이터는-seeked-또는-timeupdate-이후-일정-시간이-지나야-사용-가능-(blob-url)>) 비디오 프레임 데이터는 `'seeked'` 또는 `'timeupdate'` 이벤트 이후 일정 시간이 지나야 사용할 수 있습니다.### 🔍 비디오 프레임 데이터는 `'seeked'` 또는 `'timeupdate'` 이후 일정 시간이 지나야 사용 가능 (Blob URL)Blob URL에 대해서도 `'seeked'` 및 `'timeupdate'` 이벤트를 사용할 수 있습니다. 다만 **비디오 프레임 데이터를 사용한다면 일정 시간을 기다려야 합니다**. 경험적으로 80~100ms 이후 접근이 가능했습니다.HTTP URL과 달리, Blob URL은 이벤트가 트리거 된 직후 프레임 데이터가 없을 수 있습니다. 심지어 [`readyState`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/readyState)가 "HAVE_ENOUGH_DATA"를 의미하는 `4` 인 경우에도 말이죠! 이는 Blob URL이 로컬 파일을 참조하기 때문으로 추정됩니다[^3]. 비디오 데이터가 디코딩되어 메모리에 로드될 때 지연이 발생할 수 있습니다.[^3]: 예제 코드에서는 `File` 객체를 사용해 Blob URL을 생성합니다. 그리고 `File` 객체는 로컬 파일 시스템의 파일을 참조합니다. ("`File` 인터페이스는 파일에 대한 정보를 제공하고, 웹 페이지에서 JavaScript를 통해 해당 콘텐츠에 접근할 수 있도록 도와줍니다." - [MDN](https://developer.mozilla.org/en-US/docs/Web/API/File))# 비디오 프레임 여러 개 추출하기## w/ HTTP URL```jsconst THUMBNAIL_POSITION_LIST = [ 0, 1.1, 2.2, 3.3, 4.4, 5.5, 4.6, 3.7, 2.8, 1.9, 0,];const main = async () => { for (const thumbnailPosition of THUMBNAIL_POSITION_LIST) { const correctedThumbnailPosition = thumbnailPosition || 0.001; const video = document.createElement('video'); video.crossOrigin = 'anonymous'; video.preload = 'metadata'; video.src = `https://cdn.jsdelivr.net/gh/Gumball12/public-timer-mp4/timer.mp4#t=${correctedThumbnailPosition}`; generateThumbnail(video, thumbnailPosition); }};const generateThumbnail = (video, thumbnailPosition) => { const img = document.createElement('img'); document.body.appendChild(img); video.addEventListener('seeked', () => { const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); canvas.toBlob(blob => (img.src = URL.createObjectURL(blob))); }); video.currentTime = thumbnailPosition;};main();```[CodePen](https://codepen.io/Gumball12/pen/pomNYya?editors=0110)- [🔍](#crossorigin-anonymous로-설정해-캔버스-요소에-대한-securityerror-피하기 'Move to Reason') `crossOrigin` 애트리뷰트는 `'anonymous'`로 설정해야 합니다.- [🔍](#preload-애트리뷰트 'Move to Reason') `preload` 애트리뷰트 값을 `metadata`로 설정할 필요는 없지만, 프레임 추출이 지연될 수 있습니다.- [🔍](#media-fragments-uri 'Move to Reason') `#t=${time}` 을 이용해 프레임 위치를 지정할 수 있습니다.- [🔍](<#비디오-프레임-데이터는-seeked-또는-timeupdate-이벤트-이후에-사용-가능-(http-url)> 'Move to Reason') 비디오 프레임 데이터는 `'seeked'` 또는 `'timeupdate'` 이벤트 이후에 사용할 수 있습니다.## w/ Blob URL```jsconst input = document.createElement('input');input.type = 'file';input.accept = 'video/*';document.body.appendChild(input);input.addEventListener('change', async ({ target }) => { const file = target.files[0]; const src = URL.createObjectURL(file); const THUMBNAIL_POSITION_LIST = [ 0, 1.1, 2.2, 3.3, 4.4, 5.5, 4.6, 3.7, 2.8, 1.9, 0, ]; for (const thumbnailPosition of THUMBNAIL_POSITION_LIST) { const video = document.createElement('video'); video.preload = 'metadata'; video.src = src; await generateThumbnail(video, thumbnailPosition); }});const generateThumbnail = (video, thumbnailPosition) => new Promise(resolve => { video.addEventListener('seeked', async () => { await new Promise(resolve => setTimeout(resolve, 100)); const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); canvas.toBlob(blob => { const img = document.createElement('img'); img.src = URL.createObjectURL(blob); document.body.appendChild(img); resolve(); }); }); video.addEventListener('loadedmetadata', () => setTimeout(() => (video.currentTime = thumbnailPosition), 1), ); });```[CodePen](https://codepen.io/Gumball12/pen/jOoVJMY?editors=0110)- [🔍](#blob-url-사용-시-preload-metadata로-설정 'Move to Reason') Blob URL 사용 시, `preload`는 반드시 `'metadata'`여야 합니다. `'auto'`는 동작하지 않습니다.- [🔍](#스레드-블로킹으로-인해-잘못된-프레임-추출-가능 'Move to Reason') 스레드 블로킹을 피하기 위해, `Promise`를 사용해 프레임을 순차적으로 추출해야 합니다.- [🔍](<#비디오-프레임-데이터는-seeked-또는-timeupdate-이후-일정-시간이-지나야-사용-가능-(blob-url)>) 비디오 프레임 데이터는 `'seeked'` 또는 `'timeupdate'` 이벤트 이후 일정 시간이 지나야 사용할 수 있습니다.### 🔍 스레드 블로킹으로 인해 잘못된 프레임 추출 가능프레임 여러 개를 추출하는 경우 스레드 블로킹이 발생할 수 있습니다. 그리고 만약 스레드 블로킹이 발생한다면, **프레임이 제대로 추출되지 않을 수 있습니다**. 이 경우 [투명 이미지](#thumbnail-issue)가 생성됩니다.![프레임 일괄 추출 시도](/images/240528/attempt-to-generate-thumbnails-all-at-once.png) _프레임 일괄 추출 시도 ([타임라인 원본 데이터](/images/240528/attempt-to-generate-thumbnails-all-at-once.json))_위 이미지는 영상 내 모든 프레임을 한 번에 추출하려고 시도한 결과입니다. 특정 범위에 네트워크 요청이 집중되어 있고, 메인 스레드 역시 장시간 지속적으로 사용되고 있습니다. 그 결과 스레드 블로킹이 발생되어, 투명한 이미지가 생성되었습니다.이를 방지하기 위해 여기서는 `Promise`를 사용해 순차적으로 프레임을 추출했습니다. `generateThumbnail` 함수는 `Promise`를 반환하고, `await`을 사용해 각 프레임이 추출될 때까지 기다렸습니다.![순차적으로 프레임 추출 시도](/images/240528/generate-thumbnails-sequentially.png) _순차적으로 프레임 추출 시도 ([타임라인 원본 데이터](/images/240528/generate-thumbnails-sequentially.json))_위 이미지는 프레임을 순차적으로 추출한 결과입니다. 네트워크 요청이 고르게 분산되고, 메인 스레드가 짧은 시간 동안만 사용되었습니다. 따라서 스레드 블로킹은 발생되지 않았고, 프레임을 올바르게 추출할 수 있었습니다.# 그 외## `requestVideoFrameCallback`이벤트 대신 [`requestVideoFrameCallback`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestVideoFrameCallback)을 사용할 수도 있습니다. 다만 이 함수는 [FireFox에서 지원하지 않기 때문에](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestVideoFrameCallback#browser_compatibility), 고려하지 않았습니다.이 함수에 대해 더 알고 싶다면 [web.dev](https://web.dev/articles/requestvideoframecallback-rvfc?hl=en)를 참고해 주세요.# 맺으며저는 아이폰을 사용하고, 꽤 매력적인 기기라고 생각합니다. 그러나 독특한 iOS Safari 구현은 가끔씩 예상치 못한 도전과제를 안겨주곤 합니다. 표준과 다른 동작 방식은 다소 낯설고 어려울 수 있지만, 플랫폼이 갖는 미묘한 차이점을 이해하고 극복하는 것은 사용자 겸험을 한층 더 향상시키는 중요한 요소입니다. 그리고 이를 해결해 나가는 과정에서 얻는 성취감은 그만큼 값집니다.이번 글에서는 "iOS Safari에서 비디오 프레임을 올바르게 추출하는 방법"에 대해 다루어 보았습니다. 다양한 접근 방식과 그에 따른 이유를 살펴보며, 실제로 적용 가능한 코드를 통해 문제를 해결하는 과정을 공유했습니다. 저는 이 글이 여러분과 여러분이 만드는 서비스에 도움이 되기를 진심으로 바랍니다. 여러분이 직면한 유사한 문제들을 해결하는 데 조금이나마 도움이 되기를 바랍니다. 읽어주셔서 감사합니다!

How to Extract Video Frames Correctly in iOS Safari 🔍

shj — Thu, 13 Jun 2024 00:00:00 GMT

[Korean](./extracting-video-frames-correctly-in-ios-safari-ko.html)> NOTE: These methods have been tested on iOS Safari versions 14+ (up to 17.4.1).> Looking for an NPM package? Check out the [generate-video-dumbnail](https://npmjs.com/package/generate-video-dumbnail)!![Frame Extraction Issue](/images/240528/existing-issue.png) _Frame extraction in iOS did not work as expected_I recently worked on extracting video frames. It wasn't too difficult. I quickly put together the code with a bit of inference, ChatGPT, and Googling.```jsconst canvas = document.createElement('canvas');const ctx = canvas.getContext('2d');video.addEventListener('loadeddata', () => { canvas.width = video.videoWidth; canvas.height = video.videoHeight; ctx.drawImage(video, 0, 0, canvas.width, canvas.height); const thumbnailDataUrl = canvas.toDataURL('image/png'); document.querySelector('img').src = thumbnailDataUrl;});```The frame extraction code using the Canvas API worked well in macOS Safari and Chrome. I thought I could finish the task earlier than expected. However, when I checked it in iOS Safari... **NOTHING APPEARED!** Something was wrong. 🤯![Browser Specific Failures graph](/images/240528/browser-failures.png) _Browser Specific Failures Graph ([Source](https://wpt.fyi/results/?label=master&label=experimental&aligned))_Have you ever faced a similar situation? iOS Safari is sleek and sophisticated, but it can be a pain for web frontend developers. In this article, **I'll explain how to extract video frames in iOS Safari and Why it's necessary**. I also provide online demos for you to test.I don't know how long the frame extraction issue will last, but at least for now, this guide will help you extract frames as intended. I hope this content is helpful.> [!NOTE] Before you begin> This article is in no particular order! Instead of reading from the top to the bottom, you can jump right in and read what you need.> The titles without the magnifying glass (🔍) stand for each situation. The content shows the solution (code) first, followed by a brief reason for it. The reasons are preceded by a magnifying glass (🔍), which you can click to see a more detailed explanation.# Display Video Poster## w/ Static Video Element```html```[CodePen](https://codepen.io/Gumball12/pen/eYaBjOK?editors=1100)- [🔍](#media-fragments-uri 'Move to Reason') Append `#t=0.001` to the end of the `src` attribute to show the first frame of the video.- [🔍](#preload-attribute 'Move to Reason') `preload` attribute does not need to be set to `'metadata'`, but this may delay frame extraction.- Video can be delivered via HTTP or HTTPS.### 🔍 Media Fragments URIiOS Safari **does not display the first frame** of a video element by default! Even setting the `preload="metadata"` or `preload="auto"` attribute does not work. Instead, you must use a [Media Fragments URI](https://www.w3.org/TR/media-frags/#introduction). ([Can I Use](https://caniuse.com/media-fragments))By using one of the Media Fragments, `#t=`, you can specify a particular time in the video (in seconds). In iOS Safari, you can use this approach to show video frame(poster). For example, if you specify 0.001 seconds(`#t=0.001`), it will show the first frame. Note that setting it to `#t=0` does not load the frame.### 🔍 Preload AttributeWhile loading metadata, [some video frame data can be retrieved](https://www.w3.org/html/wiki/Elements/video#HTML_Attributes). Therefore, the `preload` attribute can be set to `'metadata'` instead of `'auto'`. Note that the default value of `preload` in iOS Safari is `'auto'`, but it may vary depending on the device state(for example, in battery saving mode). For this reason, it is recommended to set it explicitly.## w/ Dynamic Video Element (HTTP URL)```jsconst video = document.createElement('video');document.body.appendChild(video);video.preload = 'metadata';video.src = 'https://cdn.jsdelivr.net/gh/Gumball12/public-timer-mp4/timer.mp4#t=0.001';```[CodePen](https://codepen.io/Gumball12/pen/wvboxGd?editors=0110)- [🔍](#media-fragments-uri 'Move to Reason') Append `#t=0.001` to the end of the `src` attribute to show the first frame of the video.- [🔍](#preload-attribute 'Move to Reason') `preload` attribute does not need to be set to `'metadata'`, but this may delay frame extraction.- **Video data must be delivered via HTTPS**. For security reasons, the `src` attribute of dynamically created video elements must always use HTTPS.## w/ Dynamic Video Element (Blob URL)```jsconst input = document.createElement('input');input.type = 'file';input.accept = 'video/*';document.body.appendChild(input);input.addEventListener('change', ({ target }) => { const file = target.files[0]; const url = URL.createObjectURL(file); const video = document.createElement('video'); document.body.appendChild(video); video.src = url; video.preload = 'metadata'; video.currentTime = 0.001;});```[CodePen](https://codepen.io/Gumball12/pen/eYaBjzL?editors=0110)- [🔍](#set-preload-metadata-for-blob-url 'Move to Reason') When using Blob URL, the `preload` must be set to `'metadata'`. `'auto'` does not work.- [🔍](#media-fragments-uri-cannot-be-used-with-blob-url 'Move to Reason') Media Fragments URI(`#t=`) cannot be used with Blob URL. Use the `'loadedmetadata'` event to set `currentTime` to `0.001`.### 🔍 Set `preload='metadata'` for Blob URL![Preload Comparison - metadata](/images/240528/preload-metadata.png) ![Preload Comparison - auto](/images/240528/preload-auto.png) _Comparison of `preload = 'metadata'` vs. `preload = 'auto'` network requests_When creating a video element using Blob URL, **setting `preload` to `'auto'` does not retrieve frame data** at the specified time. In fact, checking the network requests(image above), you can see that `preload="metadata"` retrieves data (Bytes) in the range 48-1541 to display the first frame. However, `preload="auto"` does not retrieve data.Unfortunately, I could not find a technical reason for these differences. I used [this code](https://codepen.io/Gumball12/pen/PovpONw?editors=0010) and tested it on iOS Safari 17.4.1.### 🔍 Media Fragments URI cannot be used with Blob URLIn the current latest WebKit (Safari 17.4.1), **Media Fragments URI (e.g., `#t=`) cannot be used with Blob URL.** The relevant changes can be found in [this commit](https://github.com/WebKit/WebKit/commit/7f2ea8fcf41a68add90efab89609218407e1a824#diff-015bfbdb65247b7b4cc8319b4798e660d9c6b9df998610f579376a6db3f28f24L274-L275)[^1]. Below is part of the commit:```diffBlobData* BlobRegistryImpl::getBlobDataFromURL(const URL& url, const std::optional& topOrigin) const{ ASSERT(isMainThread());- if (url.hasFragmentIdentifier())- return m_blobs.get(url.viewWithoutFragmentIdentifier());- return m_blobs.get(url.string());+ auto urlKey = url.stringWithoutFragmentIdentifier();+ auto* blobData = m_blobs.get(urlKey);+ if (m_allowedBlobURLTopOrigins && topOrigin && topOrigin != m_allowedBlobURLTopOrigins->get(urlKey)) {+ RELEASE_LOG_ERROR(Network, "BlobRegistryImpl::getBlobDataFromURL: (%p) Requested blob URL with incorrect top origin.", this);+ return nullptr;+ }+ return blobData;}```The `URL::hasFragmentIdentifier` function, which checks for the use of Media Fragment URI, has been removed. Instead, the `URL::stringWithoutFragmentIdentifier` function, which returns a string without the Media Fragment URI, is used. Therefore, you need to use `currentTime` instead of the Media Fragment URI.From the code history, it appears that Media Fragment URI was previously supported for Blob URL. This can be confirmed in the [Safari Technology Preview 118 release notes](https://webkit.org/blog/11439/release-notes-for-safari-technology-preview-118) and the [related commit](https://github.com/WebKit/WebKit/commit/cce9f0c257eca20126d3c3d22e97e339d5718264#diff-015bfbdb65247b7b4cc8319b4798e660d9c6b9df998610f579376a6db3f28f24).[^1]: This commit appears to resolve issues related to Blob Partitioning. Blob Partitioning is a technology that divides Blobs into smaller chunks to efficiently process large data and provide fast responses to users. This feature was introduced in [Safari 17.2(19671.1.17)](https://developer.apple.com/documentation/safari-release-notes/safari-17_2-release-notes#New-Features).# Extract Single Video Frame## w/ HTTP URL```jsconst THUMBNAIL_POSITION = 5.3;const video = document.createElement('video');video.crossOrigin = 'anonymous';video.preload = 'metadata';video.src = `https://cdn.jsdelivr.net/gh/Gumball12/public-timer-mp4/timer.mp4#t=${THUMBNAIL_POSITION}`;video.addEventListener('seeked', () => { const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); canvas.toBlob(blob => { const img = document.createElement('img'); img.src = URL.createObjectURL(blob); document.body.appendChild(img); });});```[CodePen](https://codepen.io/Gumball12/pen/qBGqyKd?editors=0110)- [🔍](#set-crossorigin-anonymous-to-avoid-securityerror-with-canvas-element 'Move to Reason') `crossOrigin` attribute must be set to `'anonymous'`.- [🔍](#preload-attribute 'Move to Reason') `preload` attribute does not need to be set to `'metadata'`, but this may delay frame extraction.- [🔍](<#video-frame-data-is-available-after-the-seeked-or-timeupdate-event-(http-url)> 'Move to Reason') Video frame data is available after the `'seeked'` or `'timeupdate'` event.### 🔍 Set `crossOrigin='anonymous'` to Avoid SecurityError with Canvas ElementBrowsers, by default, only allow resources from the "same origin" ([SOP, Same Origin Policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)). If the origin is different, you need to request access through [CORS (Cross-Origin Resource Sharing)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).When requesting media resources, you can set the [`crossOrigin` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to determine how to handle CORS policy. Of course, you can request media resources that exist in different origins without setting the `crossOrigin` attribute. However, **the browser consider the integrity is not guaranteed**. And when you draw this on a Canvas, it becomes a **Tainted Canvas**[^2].[^2]: If the origin is the same, the Canvas is not tainted by the SOP!![Tainted Canvas](/images/240528/tainted-canvas.webp)A tainted canvas means that the website is not allowed to share resources. In this state, pixel data cannot be accessed. Otherwise, unauthorized origins could arbitrarily leak pixel data within the image.Canvas pixel data can be accessed with `getImageData`, `toDataURL`, `toBlob`, etc. To prevent the security issues mentioned above, **these methods throw a [`SecurityError`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException#securityerror) for a tainted canvas**. That's why you need to set `crossOrigin`.There are two options available. `'anonymous'` (or an empty string `''`), which validates CORS, but does not include any credentials (cookies, HTTP Authentication headers, SSL certificates, etc.) in the request. This helps to avoid situations where sensitive user information exposed. Therefore, I used `'anonymous'` here. However, you can include credentials via the `use-credential` option if needed.### 🔍 Video frame data is available after the `'seeked'` or `'timeupdate'` event (HTTP URL)When requesting video data using an HTTP URL, frame data is available after the `'seeked'` or `'timeupdate'` event. ([⚠️ Note that Blob URL behave differently.](<#video-frame-data-is-available-a-certain-time-after-the-seeked-or-timeupdate-event-(blob-url)>))## w/ Blob URL```jsconst THUMBNAIL_POSITION = 5.3;const input = document.createElement('input');input.type = 'file';input.accept = 'video/*';document.body.appendChild(input);input.addEventListener('change', async ({ target }) => { const file = target.files[0]; const src = URL.createObjectURL(file); const video = document.createElement('video'); video.src = src; video.preload = 'metadata'; video.addEventListener('seeked', async () => { await new Promise(resolve => setTimeout(resolve, 100)); const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); canvas.toBlob(blob => { const img = document.createElement('img'); img.src = URL.createObjectURL(blob); document.body.appendChild(img); }); }); video.addEventListener( 'loadedmetadata', () => (video.currentTime = THUMBNAIL_POSITION), );});```[CodePen](https://codepen.io/Gumball12/pen/pomNGbb?editors=0110)- [🔍](#set-preload-metadata-for-blob-url 'Move to Reason') When using Blob URL, the `preload` must be set to `'metadata'`. `'auto'` does not work.- [🔍](#media-fragments-uri-cannot-be-used-with-blob-url 'Move to Reason') Media Fragments URI(`#t=`) cannot be used with Blob URL. Use the `'loadedmetadata'` event to set `currentTime`.- [🔍](<#video-frame-data-is-available-a-certain-time-after-the-seeked-or-timeupdate-event-(blob-url)> 'Move to Reason') Video frame data is available a certain time after the `'seeked'` or `'timeupdate'` event.### 🔍 Video frame data is available a certain time after the `'seeked'` or `'timeupdate'` event (Blob URL)Blob URL also support the `'seeked'` and `'timeupdate'` events. However, **if you are using the video frame data, you will need to wait a certain time**. In my experience, I've been able to access it after 80-100ms.Unlike HTTP URL, Blob URL may not have frame data immediately after the event is triggered (even when `readyState` is `4`!). This is likely because Blob URL reference local files[^3]. Delays can occur as video data is decoded and loaded into memory.[^3]: Example code generates Blob URL using a `File` object. The `File` object references a file from the local file system. ("The `File` interface provides information about files and allows JavaScript in a web page to access their content." - [MDN](https://developer.mozilla.org/en-US/docs/Web/API/File))# Extract Multiple Video Frames## w/ HTTP URL```jsconst THUMBNAIL_POSITION_LIST = [ 0, 1.1, 2.2, 3.3, 4.4, 5.5, 4.6, 3.7, 2.8, 1.9, 0,];const main = async () => { for (const thumbnailPosition of THUMBNAIL_POSITION_LIST) { const correctedThumbnailPosition = thumbnailPosition || 0.001; const video = document.createElement('video'); video.crossOrigin = 'anonymous'; video.preload = 'metadata'; video.src = `https://cdn.jsdelivr.net/gh/Gumball12/public-timer-mp4/timer.mp4#t=${correctedThumbnailPosition}`; generateThumbnail(video, thumbnailPosition); }};const generateThumbnail = (video, thumbnailPosition) => { const img = document.createElement('img'); document.body.appendChild(img); video.addEventListener('seeked', () => { const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); canvas.toBlob(blob => (img.src = URL.createObjectURL(blob))); }); video.currentTime = thumbnailPosition;};main();```[CodePen](https://codepen.io/Gumball12/pen/pomNYya?editors=0110)- [🔍](#set-crossorigin-anonymous-to-avoid-securityerror-with-canvas-element 'Move to Reason') `crossOrigin` attribute must be set to `'anonymous'`.- [🔍](#preload-attribute 'Move to Reason') `preload` attribute does not need to be set to `'metadata'`, but this may delay frame extraction.- [🔍](#media-fragments-uri 'Move to Reason') Use `#t=${time}` to specify the frame position.- [🔍](<#video-frame-data-is-available-after-the-seeked-or-timeupdate-event-(http-url)> 'Move to Reason') Video frame data is available after the `'seeked'` or `'timeupdate'` event.## w/ Blob URL```jsconst input = document.createElement('input');input.type = 'file';input.accept = 'video/*';document.body.appendChild(input);input.addEventListener('change', async ({ target }) => { const file = target.files[0]; const src = URL.createObjectURL(file); const THUMBNAIL_POSITION_LIST = [ 0, 1.1, 2.2, 3.3, 4.4, 5.5, 4.6, 3.7, 2.8, 1.9, 0, ]; for (const thumbnailPosition of THUMBNAIL_POSITION_LIST) { const video = document.createElement('video'); video.preload = 'metadata'; video.src = src; await generateThumbnail(video, thumbnailPosition); }});const generateThumbnail = (video, thumbnailPosition) => new Promise(resolve => { video.addEventListener('seeked', async () => { await new Promise(resolve => setTimeout(resolve, 100)); const canvas = document.createElement('canvas'); canvas.width = video.videoWidth; canvas.height = video.videoHeight; const ctx = canvas.getContext('2d'); ctx.drawImage(video, 0, 0, canvas.width, canvas.height); canvas.toBlob(blob => { const img = document.createElement('img'); img.src = URL.createObjectURL(blob); document.body.appendChild(img); resolve(); }); }); video.addEventListener('loadedmetadata', () => setTimeout(() => (video.currentTime = thumbnailPosition), 1), ); });```[CodePen](https://codepen.io/Gumball12/pen/jOoVJMY?editors=0110)- [🔍](#set-preload-metadata-for-blob-url 'Move to Reason') When using Blob URL, the `preload` must be set to `'metadata'`. `'auto'` does not work.- [🔍](#incorrect-frames-may-be-extracted-due-to-thread-blocking 'Move to Reason') To prevent thread blocking, use `Promise` to extract frames sequentially.- [🔍](<#video-frame-data-is-available-a-certain-time-after-the-seeked-or-timeupdate-event-(blob-url)> 'Move to Reason') Video frame data is available a certain time after the `'seeked'` or `'timeupdate'` event.### 🔍 Incorrect frames may be extracted due to thread blockingThread blocking can occur when extracting multiple frames. If thread blocking occurs, **frames may not be extracted correctly**. In other words, [transparent images](#thumbnail-issue) are generated.![Attempting to extract frames all at once](/images/240528/attempt-to-generate-thumbnails-all-at-once.png) _Attempting to extract frames all at once ([Timeline Raw Data](/images/240528/attempt-to-generate-thumbnails-all-at-once.json))_The above image shows the result of attempting to extract all frames at once. Frequent network requests are occurring, with a concentration in a specific range. Additionally, the main thread is being used continuously for an extended period. As a result, thread blocking occurs, and transparent images are generated.To avoid this, I used `Promise` to extract frames sequentially. The `generateThumbnail` function returns a `Promise`, and I used `await` to wait for each frame to be extracted.![Extracting frames sequentially](/images/240528/generate-thumbnails-sequentially.png) _Extracting frames sequentially ([Timeline Raw Data](/images/240528/generate-thumbnails-sequentially.json))_Extracting frames sequentially ensures that network requests are evenly distributed, and the main thread is used only for a short period. This prevents thread blocking and ensures that frames are extracted correctly.# Miscellaneous## `requestVideoFrameCallback`Instead of events, you can also use [`requestVideoFrameCallback`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestVideoFrameCallback). However, this function [is not supported by FireFox](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestVideoFrameCallback#browser_compatibility), so it was not considered.To learn more about this function, please refer to [web.dev](https://web.dev/articles/requestvideoframecallback-rvfc?hl=en).# ConclusionI use an iPhone and find it to be a truly fascinating device. However, the unique implementation of iOS Safari can sometimes present unexpected challenges. The non-standard behavior may feel unfamiliar and daunting, but understanding and overcoming the subtle differences of the platform is a crucial aspect of enhancing user experience. Moreover, the sense of accomplishment that comes with solving these issues is invaluable.In this article, we've covered "How to Correctly Extract Video Frames in iOS Safari". We explored various approaches and their underlying reasons, sharing the process of solving the problem with practical, applicable code. I sincerely hope that this article is helpful to you and the services you create. May it assist you in resolving similar issues you may encounter. Thank you for reading!> This article was translated from Korean using ChatGPT and DeepL.

웹 컴포넌트 튜토리얼

shj — Sat, 11 Nov 2023 00:00:00 GMT

> 이 글은 [MDN 웹 컴포넌트 튜토리얼](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)을 많은 부분 참고해 작성한 글이다. 바로 실행할 수 있는 예제와 함께 조금 더 친절하고 이해하기 쉽도록 설명하고자 했다.# TL;DR- 웹 컴포넌트는 재사용할 수 있는 사용자 인터페이스 요소를 만드는 기술이다.- 웹 컴포넌트는 [커스텀 엘리먼트](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)와 [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)을 이용해 구현된다.- 커스텀 엘리먼트는 HTML 태그처럼 사용할 수 있는 커스텀 DOM 엘리먼트이다.- Shadow DOM은 DOM과 CSS를 캡슐화하는 기술이다.# 커스텀 엘리먼트 만들어 보기웹 컴포넌트는 재사용할 수 있는 커스텀 엘리먼트를 만들 수 있게 해준다. 커스텀 엘리먼트는 일반적인 HTML 태그처럼, 또는 JavaScript을 이용해 사용할 수 있다. 이는 [`CustomElementRegistry.define`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) 메서드를 이용하는데, `window.customElements` 객체를 통해 접근할 수 있다.```js// customElements.define() 으로도 접근이 가능window.customElements.define(/* ... */);```이 메서드는 인자 세 개를 전달받아 커스텀 엘리먼트를 등록(Registry)한다:- `name`: 커스텀 엘리먼트 이름이며, [커스텀 엘리먼트 이름 규칙](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define#valid_custom_element_names)을 따라야 한다. 가령 반드시 하이픈(`-`)을 포함해야 한다.- `constructor`: 커스텀 엘리먼트 행동을 정의하는 클래스. 이 클래스는 [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)를 상속받아야 한다.- `options`: 커스텀 엘리먼트 기능을 확장하는 객체. 현재(2024.03)는 `extends` 옵션만을 지원한다. 커스텀 엘리먼트가 상속받을 [빌트인 HTML 엘리먼트](https://developer.mozilla.org/en-US/docs/Web/HTML/Element)를 확장할 수 있다.가령 다음과 같이 `WordCount` 라는 커스텀 엘리먼트 정의가 가능하다.```javascriptclass WordCount extends HTMLParagraphElement { constructor() { super(); // 반드시 호출 // 커스텀 엘리먼트 기능 }}customElements.define('word-count', WordCount, { extends: 'p' });```등록 이후에는 `WordCount` 커스텀 엘리먼트를 사용할 수 있다.```html

``````jsdocument.createElement('word-count');// ordocument.createElement('p', { is: 'word-count' });```이 외에도 커스텀 엘리먼트 생성, 제거, 애트리뷰트 변경 등 이벤트를 감지할 수 있는 [커스텀 엘리먼트 라이프사이클 콜백](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks)이 있다. 자세한 내용은 아래에서 다루도록 한다.## 예제를 통해 알아보기여기서는 다음 기능을 수행하는 커스텀 엘리먼트를 만들어 보도록 한다. 이름은 `popup-info`로 하자.- 이미지 아이콘과 텍스트로 구성- 텍스트는 기본적으로 숨겨져 있고, 아이콘은 항상 보임- 아이콘에 마우스를 올리면 텍스트가 보임어렵지 않다. `HTMLElement`를 상속받는 `PopupInfo` 클래스를 만들고, `constructor`에 필요한 기능을 구현하면 된다. 항상 `super()`를 호출해야 한다는 점을 잊지 말자.```jsclass PopupInfo extends HTMLElement { constructor() { super(); // Shadow DOM 생성 this.attachShadow({ mode: 'open' }); // 아이콘 및 텍스트 엘리먼트 생성 const wrapper = document.createElement('div'); wrapper.classList.add('wrapper'); const icon = wrapper.appendChild(document.createElement('span')); icon.classList.add('icon'); icon.addEventListener('click', () => wrapper.classList.toggle('popup')); const img = icon.appendChild(document.createElement('img')); img.src = this.getAttribute('img') ?? 'https://placeholder.com/100x100'; const info = wrapper.appendChild(document.createElement('span')); info.classList.add('info'); info.textContent = this.getAttribute('data-info') ?? ''; const style = document.createElement('style'); style.textContent = ` .wrapper.popup .info { display: block; } .info { display: none; } `; // 엘리먼트를 Shadow DOM에 추가 this.shadowRoot.append(style, wrapper); }}// 커스텀 엘리먼트 등록customElements.define('popup-info', PopupInfo);```> 💡> Shadow DOM(Shadow Root)은 CSS와 DOM을 캡슐화할 수 있는 독립된 DOM 트리라고 생각하면 된다. 여기서는 `attachShadow` 메서드를 통해 Shadow DOM을 생성하고, `shadowRoot` 프로퍼티를 통해 Shadow DOM에 접근할 수 있다는 점만 알아두자. 자세한 내용은 아래에서 다루도록 한다.`constructor` 내부에서 `this.getAttribute`를 통해 애트리뷰트 값을 가져올 수 있다. `this.hasAttribute`를 통해 애트리뷰트 존재 여부를 확인할 수도 있다. 이를 통해 `img` 애트리뷰트가 존재하지 않을 경우 기본 이미지를 사용하도록 했다.스타일은 `style` 엘리먼트를 생성해 `textContent`에 CSS 문자열을 넣어준 뒤 Shadow DOM에 추가하는 방식을 이용했다. 스타일은 Shadow DOM 내부에서만 적용되며, 외부에는 영향을 주지 않는다.이제 `popup-info` 커스텀 엘리먼트를 사용할 수 있다.```html```[동작하는 예시 확인하기](https://codepen.io/Gumball12/pen/gOqeLWZ?editors=1010)## `extends` 옵션을 이용한 빌트인 엘리먼트 확장`extends` 옵션을 이용하면 빌트인 HTML 엘리먼트를 확장할 수 있다. 가령 `extends: 'ul'` 옵션을 사용해 만들어진 커스텀 엘리먼트는 `

Item 1

Item 2

Item 3

Simple DOM

Here we will add a link to the Mozilla

${this.info}