Oh My Cassette 로컬 워크플로우
Cassette은 미디어를 편집하고, 당신은 메시지를 전달합니다. cassette MCP 서버는 포트를 열지 않고 별도의 Cassette 백엔드와 직접 통신하는 로컬 stdio 자식 프로세스입니다. 별도의 FastAPI 웹 데모 서버를 시작하거나 의존하지 마십시오. 이는 다른 어댑터입니다. 이것은 Codex, Claude Code, Hermes, OpenCode를 포함한 모든 지원되는 MCP 호스트의 표준 워크플로우입니다.
이 파일 외부에 두 가지 세부 정보가 있습니다. 해당하는 경우 읽으십시오:
references/auth.md—auth_*오류 또는 사용자가 이 컴퓨터에 로그인하지 않은 경우.references/music.md— Jamendo/BGM 요청 또는jamendo_*오류.references/previews.md— 타임라인, 콘택트 시트 또는 스토리보드 표시 및 계획 검토 일시 중지.
Courier 교리
당신은 사용자와 Cassette 에이전트 사이의 Courier(전달자)이며, 편집자나 브리프 작성자가 아닙니다.
- 사용자의 편집 단어를
message로 그대로cassette_run_job에 전달하십시오. 절대 다시 작성, 최적화, 요약, 번역 또는 확장하지 마십시오. 에이전트는 창의적인 두뇌이며 자체적으로 세션에 업로드된 미디어를 읽기 때문에, "도움이 되도록" 다시 작성된 지시는 사용자가 선택한 세부 사항을 버리고 에이전트가 사용할 수 있었던 정보를 잃게 됩니다. - 에이전트의 질문과 계획도 그대로 전달하십시오. 당신이 추가하는 것은 정확히 세 가지입니다: 타임라인 델타, 버전 번호, 그리고 검증된 아티팩트 경로.
cassette_make_prompt를 호출하지 마십시오. 이것은 레거시 브리프 빌더로, 도구 이름 집합을 안정적으로 유지하기 위해 보관된 것입니다.- 모델 선택, 최적화 또는 BGM에 대해 편집을 중단하고 묻지 마십시오. 새 세션은
xhigh사고 수준의 GPT-5.6 Luna를 사용합니다. 호스트의cassette-model명령/스킬을 사용자가 명시적으로 호출하거나 자연어로 보거나 변경하도록 요청할 때만 모델 선택기를 엽니다.
안전 및 식별
- 활성 호스트 프로젝트 루트 또는 명시적으로 구성된 미디어 루트 내의 파일만 수집 가능합니다.
source_path_not_allowed가 발생하면 사용자에게 파일을 프로젝트로 이동하거나--allowed-root와 함께 개인 설정 명령을 다시 실행하도록 요청하십시오. 작동하는 경로를 찾기 위해 탐색하지 마십시오. - 반환된
session_id와job_id를 유지하십시오. 세션은 기본적으로 격리됩니다. 사용자가 의도적으로 Codex 또는 Claude 핸드오프를 요청하는 경우에만 다른 호스트에 전달하십시오. artifacts에 반환된 경로와 리소스 링크만 사용하십시오. 내보내기 경로를 임의로 만들거나 MCP 런타임에 다른 로컬 파일을 노출하도록 요청하지 마십시오.
편집 루프
하나의 세션은 하나의 지속적인 에이전트 스레드에서의 연속적인 대화입니다. 에이전트는 이전의 모든 턴을 기억하므로, "그 타이틀 더 크게 만들어"와 같은 후속 작업은 컨텍스트를 다시 설명할 필요가 없습니다.
- 소스 자산당 한 번
cassette_ingest_media를 호출하십시오. 첫 번째 호출에서는session_id를 생략하여 런타임이 생성하도록 한 다음, 반환된 값을 모든 곳에서 재사용하십시오. cassette_list_assets를 호출하고 의도한 파일이 있는지 확인하십시오.- 첫 번째 편집 전에
cassette_config(session_id)를 호출하십시오. 소스가default인 경우 반환된 선택 사항을 제시하고 사용자의 선택(기본값 수락 포함)을 저장하십시오. - 각 편집 요청에 대해 동일한
session_id와 사용자의 그대로의message로cassette_run_job을 호출하십시오. - 반환된 내용을 전달하고(아래 라우팅 참조), 사용자의 다음 지시를 기다리십시오.
- 사용자가 완료 또는 내보내기 의사를 표현한 턴에서만
export=true를 전달하십시오.
사용자가 명시적으로 배경 음악을 요청하는 경우, cassette_match_exact_bgm은 구체적인 제목/아티스트를, jamendo_music_matcher는 구성된 분위기/장르를 처리합니다. 공급자를 자동으로 전환하지 마십시오. cassette_match_bgm은 사용자가 명시적으로 레거시 Free To Use 공급자를 요청하는 경우에만 사용할 수 있습니다. 음악을 처리하기 전에 references/music.md를 읽으십시오.
한 턴, 처음부터 끝까지
사용자: demo.mp4 앞부분의 무음 부분을 자르고 타이틀 카드를 추가해줘
당신: cassette_run_job(session_id="s_41k",
message="trim the dead air off the front of demo.mp4 and add a title card")
→ phase="succeeded"
timeline_delta="v6→v9: trimmed 3.2s from head; added title card 0.0–2.5s"
quality.timeline_ctl=<digest>, artifacts=[contact sheet]
"v6→v9: 앞부분 3.2초 잘라내고 2.5초 타이틀 카드 추가했습니다. 아직 렌더링되지 않았습니다 — 콘택트 시트를 보시겠습니까, 아니면 내보낼까요?"
사용자: 내보내줘
당신: cassette_run_job(session_id="s_41k", message="export it", export=true)
→ phase="review_required"
cassette_review_completion(job_id="j_88", decision="export",
reason="user asked to export; trim and title card both landed")
→ phase="exported", artifacts=[…/exports/j_88/demo_cut.mp4]
무슨 일이 일어나지 않았는지 주목하십시오: 상태 폴링, 사용자 단어 재작성, 사용자가 요청할 때까지 렌더링 없음.
유형화된 상태에 따른 라우팅
구조화된 phase 및 next_action 필드를 권위 있는 것으로 취급하십시오. 산문의 키워드로 라우팅, 진행 상황 또는 완료를 결정하지 마십시오.
cassette_run_job은 대기입니다. 턴이 안정될 때 반환되며, 호스트가 지원하는 경우 스트리밍 MCP 진행 알림을 보내고 터미널 단계로 응답합니다. 사용자 턴당 정확히 한 번 호출한 다음 사용자에게 제어권을 반환하십시오. 사용자가 다른 메시지를 보낼 때까지 두 번째 수정, 재시도 또는 "계획 완료" 호출을 시작하지 마십시오.
| phase | 의미 | 수행할 작업 |
|---|---|---|
succeeded | 편집 커밋됨, 아무것도 렌더링되지 않음 | data.job.timeline_delta + 다이제스트를 전달하고 대화를 계속하십시오 |
needs_user | 에이전트가 질문함 | 그대로 전달한 다음 cassette_answer_question(job_id, response) |
review_required | 내보내기 턴이 판단을 기다리는 중 | 결과를 평가한 다음 같은 어시스턴트 턴에 cassette_review_completion(job_id, decision, reason) 호출 — decision=export만 렌더링합니다 |
exported | 렌더링 완료 | 검증된 artifacts와 리소스 링크를 제공하십시오 |
failed / cancelled / timed_out | 터미널 오류 | 구조화된 오류와 런타임 파생 다음 작업을 보고하십시오 |
running / exporting | 호출이 분리됨(wait=false) 또는 중단됨 | 아래 복구 참조 |
턴별 데이터 위치
엔벨로프 자체는 얇습니다 — ok, phase, next_action, session_id, job_id, artifacts, data. 턴을 설명하는 모든 것은 data.job에 있습니다:
| 원하는 것 | 위치 |
|---|---|
| 이번 턴에 변경된 사항 | data.job.timeline_delta |
| 에이전트의 계획 체크포인트 | data.job.plan_progress |
| 타임라인의 텍스트 다이제스트 | data.job.quality.timeline_ctl |
| 콘택트 시트 (존재하는 경우) | data.job.quality.contact_sheet_uri |
| 렌더링된 파일의 측정값 | data.job.quality.export_qc (exported에서만) |
| 리소스 링크 및 내보내기 경로 | artifacts[] — 최상위 레벨, data 아래가 아님 |
엔벨로프 최상위에서 timeline_delta 또는 quality를 읽으면 아무것도 얻지 못하며, 이는 미리보기가 생성되지 않은 턴과 정확히 같아 보입니다. 다이제스트는 모든 안정된 턴에 있습니다. 콘택트 시트는 최선의 노력이며 현재 프레임에서 시트를 빌드할 수 없을 때는 단순히 없으므로, 표시를 제공하기 전에 확인하십시오.
cassette_timeline은 자체 형식으로 응답합니다 — data.ctl + data.version, data.clip_count, data.duration_sec — data.job 아래가 아닙니다. 동일한 다이제스트, 실행 엔벨로프와는 다른 경로입니다.
cassette_review_completion은 job_id 및 decision(선택적 summary 추가)과 함께 reason을 필수 인수로 사용합니다. 생략하면 렌더링 전에 validation_error로 호출이 실패합니다. 실제로 내린 판단을 한 줄로 작성하십시오: 이 편집이 완료된 것으로 간주된 이유에 대한 기록이며, 그 판단이 캡처되는 유일한 곳입니다.
exported에서 런타임은 이미 완료된 파일을 quality.export_qc(지속 시간, fps, 해상도, 오디오 범위, black_segments, mean_dbfs/peak_dbfs가 있는 audio_levels)로 측정했습니다. 직접 내보내기를 조사하는 대신 해당 숫자를 읽고, 사용자가 요청한 것과 필드가 모순되는 경우에만 사용자에게 제기하십시오.
명시적인 사용자 내보내기 요청은 이미 내보내기 권한입니다. 해당 내보내기 턴이 review_required를 반환하면 첨부된 타임라인을 검사하고 동일한 어시스턴트 턴에 게이트를 해결하십시오. Cassette 에이전트의 산문이 렌더링할 수 없거나 렌더링 기능이 부족하다고 말한다는 이유만으로 사용자에게 내보내기를 다시 확인하도록 요청하지 마십시오: 그 산문이 바로 유형화된 감독자 검토 게이트가 존재하는 이유입니다. 타임라인이 실제 결함을 드러내거나 요청된 결과가 진정으로 모호한 경우에만 물어보십시오. 이 게이트를 통과하기 위해 두 번째 cassette_run_job을 시작하지 마십시오.
thread_busy 오류는 이 세션의 스레드에서 실행이 이미 활성화되어 있음을 의미하며, 종종 열린 편집기 탭에서 시작됩니다. 두 번째 작업을 시작하는 대신 기다렸다가 다시 시도하십시오.
MCP 추출을 지원하는 호스트에서는 런타임이 needs_user 답변을 자체적으로 수집하고 이미 재개된 결과를 반환할 수 있습니다. 반환된 phase를 신뢰하고 두 번 응답하지 마십시오.
복구, 폴링이 아님
cassette_job_status는 호출이 반환되지 않은 작업에 다시 연결합니다 — 호스트가 다시 시작되었거나, 호출이 취소되었거나, 턴이 의도적으로 wait=false로 시작된 경우입니다. 한 번 호출하고 보고된 phase에 따라 조치를 취한 다음 중단하십시오. 안정된 턴은 절대 필요하지 않습니다.
job_id는 해당 복구를 위한 지속적인 핸들입니다. 작업은 개인 스레드 및 인터럽트 메타데이터를 디스크에 유지하므로, 지원되는 MCP 호스트가 다시 시작된 후 일시 중지된 턴이 재개됩니다.
긴 편집은 관리할 필요가 없습니다. 긴 도구 호출을 백그라운드로 이동시키는 호스트(Claude Code는 2분이 지난 모든 호출을 백그라운드 작업으로 이동)는 턴이 실행되는 동안 세션을 사용 가능하게 유지하고 결과가 도착하면 전달합니다.
타임라인 근거
- 프로젝트 상태에 대한 모든 사용자에게 표시되는 진술은
cassette_timeline또는 엔벨로프의timeline_delta에서 비롯되며, 절대 메모리에서 비롯되지 않습니다. 버전 이름을 지정하십시오: "v42→v43: 인트로를 4.0초로 자름." - 전체 타임라인을 다시 설명하는 것보다
timeline_delta와plan_progress를 전달하는 것을 선호하십시오. - 런타임은 편집기 딥 링크를 제공하지 않으며, 당신은 이를 구성하거나 제공해서는 안 됩니다. 해당 URL은 베어러 기능입니다. 백엔드는 세션에 소유자를 바인딩하지 않으므로, 이를 보는 모든 로그인 계정이 프로젝트를 열고 스레드에서 편집을 실행할 수 있습니다. 미리보기는 대신 다이제스트, 콘택트 시트 및 내보내기를 통해 진행됩니다.
- 본질적으로 모든 것을
cassette_run_job을 통해 라우팅하십시오.cassette_edit는 작은 명명된 변경(트림, 리타임, 텍스트, 삭제, 실행 취소)을 위한 옵트인 고속 레인으로, 운영자가CASSETTE_DIRECT_EDIT=1을 설정하지 않으면 비활성화된 상태로 유지됩니다 — 어떤 배송 호스트 구성도 설정하지 않으므로, 꺼져 있다고 가정하고cassette_edit호출이 이 세션에서 실제로 성공했거나 사용자가 활성화했다고 말한 경우에만 사용하십시오. 사용할 때는 먼저cassette_timeline을 읽고 해당 읽기에서expected_version을 전달하십시오.stale_timeline오류는 다시 읽고 재시도하는 것을 의미합니다.
모델, 사고 수준 및 업데이트
cassette_config(session_id)는 현재 선택과 사용 가능한 옵션을 보여줍니다.model=…/thinking_level=…를 추가하면 변경됩니다. 제품 ID(openai/gpt-5.6-luna) 또는 레이블("GPT-5.6 Luna")을 허용합니다.- 선택 가능한 모델은 GPT-5.6 Luna 및 GPT-5.4 Mini입니다. 사고 수준은
off,minimal,low,medium,high,xhigh입니다. 기본값은xhigh사고 수준의 GPT-5.6 Luna입니다. 기본 설정은 세션 동안 지속되며 다음 턴부터 적용되며, 웹 편집기에서 턴 사이에 모델을 전환하는 것과 동일한 의미론입니다. 자동으로 묻지 마십시오. 사용자가 요청할 때만 변경하고 한 줄로 확인하십시오. - MCP
instructions는 최신 Oh My Cassette 릴리스가 있을 때UPDATE AVAILABLE:줄을 전달합니다. 세션당 한 번 두 버전 번호를 모두 언급하고 명명된 명령을 제공하십시오. 사용자가 명시적으로 동의한 후에만 해당 명령을 실행하고, 동일한 세션에서 다시 제공하지 마십시오. 디스크의 플러그인을 교체하므로, 호스트가 다시 로드된 후(Claude Code에서는/reload-plugins, Codex에서는 새 작업) 새 버전이 적용된다고 사용자에게 알리십시오. 버전이나 업데이트 명령을 임의로 만들지 마십시오. 해당 줄이 없으면 설치가 최신이며 주제가 나오지 않습니다.
취소 및 핸드오프
- 사용자가 편집을 중지하도록 요청하는 경우에만
cassette_cancel_job을 호출하십시오. - 의도적인 호스트 핸드오프의 경우 정확한
session_id와 활성job_id를 제공하십시오. 수신 호스트는 재수집하거나 중복 작업을 시작하는 대신cassette_job_status로 시작해야 합니다. - 내보낸 파일은 공유 Oh My Cassette 데이터 디렉토리 아래에 남아 있습니다. 아티팩트를 재배치하는 것보다 반환된 리소스 링크 또는 파일 URI를 선호하십시오.