> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# get_note_transcript

> 회의 노트의 전체 대화 transcript 가져오기

## 개요

<Warning>
  **최후의 수단.** transcript는 토큰을 많이 써요(1시간짜리 회의는 30K 토큰을 넘을 수 있어요). 먼저 [`search_notes`](./search-notes)를 사용하세요. 보통 10배 더 압축적이면서 정보량은 동등한 정제된 문서(one-pager, custom)를 반환해요. 직접 인용을 위해 정확히 받아 적은 단어가 필요할 때만 이 도구를 사용하세요.
</Warning>

<Warning>
  **호환성 변경 (2026-05-06).** 응답 형태가 화자 귀속 segment 중심으로 통합됐어요. `transcription`, `paragraphs[].text`, `hasDiarization`, `totalParagraphs` 필드는 **제거**됐어요. 이제 모든 단락은 `{content, speaker}`를 담은 `segments[]` 배열을 노출해요. diarization 데이터가 있으면 `speaker`는 `{label, name}`이고, 없으면 `null`이에요. 아래 [Migration](#migration) 섹션을 참고해 새 형태에서 옛 필드를 재구성하세요.
</Warning>

`get_note_transcript`는 노트의 **전체 transcript**를 화자 귀속 segment의 단락들로, 노트 메타데이터와 함께 반환해요. 노트에 diarization 데이터가 있든 없든 형태는 동일해요. 모든 단락은 `segments[]` 배열을 가지며, 각 segment에는 `content` 문자열과 `speaker` 객체(또는 `null`)가 있어요. `content`와 `speaker.name`은 둘 다 MCP 레이어에서 HTML이 제거돼요.

**주요 사용 사례:**

* 회의에서 실제로 말한 단어를 그대로 인용.
* **누가 무엇을 말했는지** 파악. segment별 `speaker` 필드가 이 도구의 주요 사용 사례예요.
* 구조화된 `paragraphs` 배열을 사용해 transcript를 시간 범위로 잘라내기.
* 문서가 필요한 표현을 담지 못할 때 대화 맥락 분석.

**핵심 기능:**

* 일관된 형태: diarization 가용 여부와 관계없이 모든 단락이 `segments[]`를 포함해요.
* 화자 정보: `segment.speaker`는 diarization이 있으면 `{label, name}`, 없으면 `null`이에요.
* MCP 레이어에서 HTML 제거(`content`와 `speaker.name` 모두 정제됨).

<Note>
  **무료·미결제 노트는 전사가 일부 가려질 수 있어요.** 노트가 무료 사용 한도를 넘었고 유료 플랜이 아니면, 한도를 넘는 단락의 `content`가 마스킹된 채 반환돼요. 글자 수와 구조는 그대로지만 단어가 자리표시 문자로 바뀌어 실제 발화 대신 뜻 없는 텍스트로 보여요. transcript가 중간부터 깨져 보인다면 대부분 버그가 아니라 이 마스킹이에요. 유료 플랜을 시작하면 노트 잠금이 풀리고 전체 전사가 반환돼요.
</Note>

## 파라미터

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `noteGuid` | string | Yes      | 고유 노트 식별자   |

### noteGuid (필수)

가져올 노트의 고유 식별자예요.

**예시:**

```json theme={"system"}
{
  "noteGuid": "abc-123-def"
}
```

**노트 GUID를 얻는 방법:**

1. [`list_notes`](./list-notes)(가벼움)를 사용해 폴더, 날짜, keyword로 후보를 찾으세요.
2. 결과에서 `noteGuid`를 사용하세요. 맥락을 위한 문서 내용도 필요하면 먼저 [`search_notes`](./search-notes)로 가져오고, 그대로 받아 적은 발화가 필요할 때만 이 도구로 돌아오세요.

## 응답 형식

### 성공 응답 — diarization된 노트

노트에 diarization 데이터가 있으면 단락은 하나 이상의 segment를 포함하고, 각 segment의 `speaker`는 `label`(엔진이 할당하고 노트 내에서 안정적)과 `name`(해석된 사람 이름, 화자가 매핑되지 않으면 `null`)을 가진 객체예요:

```json theme={"system"}
{
  "noteGuid": "abc-123-def",
  "title": "Weekly Team Meeting",
  "participants": ["Alice Kim", "Bob Park"],
  "createdAt": "2024-01-15T10:30:00Z",
  "recordingDurationSeconds": 3625,
  "paragraphs": [
    {
      "timeFrom": "2024-01-15T10:30:05Z",
      "timeTo":   "2024-01-15T10:30:18Z",
      "segments": [
        {
          "content": "Let's start with the project update.",
          "speaker": { "label": "SPEAKER_0", "name": "Alice Kim" }
        },
        {
          "content": "Sure, I've completed the migration.",
          "speaker": { "label": "SPEAKER_1", "name": "Bob Park" }
        }
      ]
    }
  ]
}
```

### 성공 응답 — diarization되지 않은 노트

노트에 diarization 데이터가 없으면 각 단락은 `speaker`가 `null`인 단일 segment로 축약돼요. 그 외 형태는 동일하므로 호출자는 분기 없이 `paragraphs[].segments[]`를 순회할 수 있어요:

```json theme={"system"}
{
  "noteGuid": "abc-123-def",
  "title": "Solo Voice Memo",
  "participants": ["Alice Kim"],
  "createdAt": "2024-01-15T10:30:00Z",
  "recordingDurationSeconds": 120,
  "paragraphs": [
    {
      "timeFrom": "2024-01-15T10:30:05Z",
      "timeTo":   "2024-01-15T10:30:18Z",
      "segments": [
        {
          "content": "Reminder to send the contract by Friday.",
          "speaker": null
        }
      ]
    }
  ]
}
```

**필드 설명:**

| Field                                   | Type           | Description                                                    |
| --------------------------------------- | -------------- | -------------------------------------------------------------- |
| `noteGuid`                              | string         | 고유 노트 식별자.                                                     |
| `title`                                 | string         | 노트 제목.                                                         |
| `participants`                          | string\[]      | 참가자 이름(이름을 쓸 수 없으면 이메일).                                       |
| `createdAt`                             | string         | ISO 8601 생성 타임스탬프.                                             |
| `recordingDurationSeconds`              | number         | 녹음 길이(초).                                                      |
| `paragraphs[]`                          | array          | 구조화된 단락. 각 단락은 하나 이상의 화자 귀속 segment를 담은 시간 경계 청크예요.            |
| `paragraphs[].timeFrom`                 | string \| null | 단락의 ISO 8601 시작 시각.                                            |
| `paragraphs[].timeTo`                   | string \| null | 단락의 ISO 8601 종료 시각.                                            |
| `paragraphs[].segments[]`               | array          | 단락의 화자 귀속 조각들. 단락이 반환될 때는 항상 비어 있지 않아요(빈 segment와 빈 단락은 필터링됨). |
| `paragraphs[].segments[].content`       | string         | segment의 HTML 제거된 일반 텍스트 내용.                                   |
| `paragraphs[].segments[].speaker`       | object \| null | diarization 데이터가 있으면 `{label, name}`, 없으면 `null`.              |
| `paragraphs[].segments[].speaker.label` | string         | diarization 엔진 라벨(예: `SPEAKER_0`). 단일 노트 내에서 안정적.              |
| `paragraphs[].segments[].speaker.name`  | string \| null | 사용자가 화자를 매핑한 경우 해석된 사람 이름, 아니면 `null`.                         |

## Migration

2026-05-06 이전 응답은 `transcription`(연결된 문자열), `paragraphs[].text`(단락별 일반 텍스트), `hasDiarization`, `totalParagraphs`를 담았어요. 이 네 가지 모두 사라졌어요. 새 형태에서 다음과 같이 재구성할 수 있어요:

```js theme={"system"}
// Reconstruct the old `paragraphs[].text` field.
const text = paragraph.segments.map(s => s.content).join(" ");

// Reconstruct the old `transcription` joined string.
const transcription = response.paragraphs
  .map(p => {
    const ts = p.timeFrom ? `[${p.timeFrom.slice(11, 19)}] ` : "";
    return ts + p.segments.map(s => s.content).join(" ");
  })
  .join("\n");

// Reconstruct the old `hasDiarization` flag.
const hasDiarization = response.paragraphs.some(p =>
  p.segments.some(s => s.speaker !== null)
);

// Reconstruct the old `totalParagraphs` count.
const totalParagraphs = response.paragraphs.length;
```

"누가 무엇을 말했는지"가 필요하면 `segments[].speaker`를 직접 읽으세요. 그게 이 도구의 새로운 주요 사용 사례예요.

## 사용 예시

### 예시 1: 기본 사용

**AI 요청:**

```
Show me the full transcript of meeting abc-123-def
```

**MCP 호출:**

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_note_transcript",
    "arguments": {
      "noteGuid": "abc-123-def"
    }
  },
  "id": 1
}
```

**응답:**

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "result": {
    "noteGuid": "abc-123-def",
    "title": "Q4 Marketing Strategy Meeting",
    "participants": ["Sarah Kim", "John Park"],
    "createdAt": "2025-11-10T10:00:00Z",
    "recordingDurationSeconds": 3625,
    "paragraphs": [
      {
        "timeFrom": "2025-11-10T10:00:05Z",
        "timeTo":   "2025-11-10T10:00:18Z",
        "segments": [
          {
            "content": "Welcome to the Q4 marketing strategy meeting.",
            "speaker": { "label": "SPEAKER_0", "name": "Sarah Kim" }
          }
        ]
      },
      {
        "timeFrom": "2025-11-10T10:00:18Z",
        "timeTo":   "2025-11-10T10:00:42Z",
        "segments": [
          {
            "content": "Thanks. Let me present our website analytics.",
            "speaker": { "label": "SPEAKER_1", "name": "John Park" }
          }
        ]
      }
    ]
  },
  "id": 1
}
```

### 예시 2: 점진적 공개 패턴

**1단계: 검색**

```
Find recent marketing meetings
```

`search_notes` 사용 - 빠름(\~1초, \~100 토큰)

**2단계: 요약**

```
What was discussed in meeting abc-123-def?
```

`get_note(include: ['summary'])` 사용 - 중간(\~2초, \~500 토큰)

**3단계: 전체 transcript (필요할 때만)**

```
Show me the exact conversation about budget allocation
```

`get_note_transcript` 사용 - 느림(\~5초, \~4,000 토큰)

## 토큰 사용량

**일반적인 회의 (1시간):** \~3,000-5,000 토큰

2026-05-06 이전 형태와 비교하면 단일 화자 노트는 중복되던 `transcription` 연결 문자열이 더 이상 방출되지 않아 **약 30% 감소**해요. 다중 화자(diarization된) 노트는 거의 비슷해요. segment별 `speaker` 메타데이터가 옛 `transcription` 페이로드를 대체하고, segment 내용은 옛 `text` 필드가 담던 것과 같은 데이터예요.

**비교 (3단계 디스커버리):**

| Tool                               | Token Usage              | When to Use                |
| ---------------------------------- | ------------------------ | -------------------------- |
| `list_notes`                       | 노트당 \~50 토큰              | 어떤 노트가 있는지 찾기(메타데이터만)      |
| `search_notes`                     | 노트당 \~1,500 토큰           | 주제 이면의 **내용** 읽기(문서 반환)    |
| **`get_note_transcript`**          | **시간당 \~3,000-5,000 토큰** | **최후의 수단 — 인용을 위한 정확한 발화** |
| `get_note(include: ['summary'])`   | \~200-800 토큰             | 노트 하나의 빠른 AI 요약            |
| `get_note(include: ['documents'])` | \~300-2,000 토큰           | 특정 생성 문서                   |

<Tip>
  **토큰 절감**

  먼저 [`search_notes`](./search-notes)를 사용하세요. 문서 출력이 보통 원본 transcript보다 10배 더 압축적이고 "팀이 무엇을 결정했나" 같은 질문 대부분에 답해줘요. 정말로 그대로 받아 적은 표현이 필요할 때만 `get_note_transcript`를 사용하세요.
</Tip>

## 권장 사례

<AccordionGroup>
  <Accordion title="점진적 공개(3단계) 사용하기">
    항상 이 순서를 따르세요:

    1. **list\_notes** — 어떤 노트가 있는지 찾기(노트당 \~50 토큰)
    2. **search\_notes** — 매칭된 주제의 문서 읽기(노트당 \~1,500 토큰)
    3. **get\_note\_transcript** — 정확한 표현이 필요할 때만(시간당 \~4,000 토큰)

    "우리가 무엇을 결정했지?" 같은 질문 대부분은 2단계에서 멈춰요. 곧바로 transcript로 가는 것보다 최대 90%의 토큰을 절약할 수 있어요.
  </Accordion>

  <Accordion title="transcript를 언제 사용할지">
    다음이 필요할 때 전체 transcript를 사용하세요:

    * 정확한 인용이나 발언 찾기
    * 상세한 대화 흐름 분석
    * 완전한 맥락 이해
    * 특정 논의 참조
    * **누가 무엇을 말했는지** 파악. `segments[].speaker` 필드가 이를 이 도구의 주요 사용 사례로 만들어요.

    다음에는 transcript를 사용하지 마세요:

    * 빠른 개요(대신 `get_note(include: ['summary'])`)
    * action item(`get_note(include: ['documents'])`)
    * 전반적 이해(`get_note(include: ['summary'])`)
  </Accordion>

  <Accordion title="긴 transcript 처리하기">
    아주 긴 회의(2시간 이상)에서는:

    * 5,000\~10,000 토큰을 예상하세요
    * timeout(60초)이 발생할 수 있어요
    * 먼저 요약으로 특정 섹션을 요청하는 것을 고려하세요
    * 전체 transcript를 불러오기 전에 요약으로 관련 부분을 파악하세요
  </Accordion>
</AccordionGroup>

## 자주 발생하는 오류

### 노트 GUID 누락

<Error>
  ```json theme={"system"}
  {
    "error": "noteGuid is required",
    "code": "MISSING_NOTE_GUID",
    "statusCode": 400
  }
  ```
</Error>

**해결 방법:** `noteGuid` 파라미터를 제공하세요.

### 노트를 찾을 수 없음

<Error>
  ```json theme={"system"}
  {
    "error": "Note not found",
    "code": "NOTE_NOT_FOUND",
    "statusCode": 404
  }
  ```
</Error>

**가능한 원인:**

* 노트가 존재하지 않음
* 노트가 삭제됨
* 이 노트에 접근할 권한이 없음

**해결 방법:** `search_notes`로 노트 GUID를 확인하세요.

### 요청 timeout

<Error>
  ```json theme={"system"}
  {
    "error": "Request timeout",
    "code": "REQUEST_TIMEOUT",
    "statusCode": 504
  }
  ```
</Error>

**원인:**

* 아주 긴 회의 transcript(2시간 이상)
* 서버 부하

**해결 방법:**

1. 대신 `get_note(include: ['summary'])`를 사용하세요
2. 잠시 후 재시도하세요
3. 문제가 계속되면 지원팀에 문의하세요

## 성능

**응답 시간:**

| Meeting Length | Tokens   | Response Time    |
| -------------- | -------- | ---------------- |
| 30분            | \~1,500  | \~2초             |
| 1시간            | \~3,000  | \~3초             |
| 2시간            | \~6,000  | \~5초             |
| 3시간 이상         | \~9,000+ | \~8초(timeout 가능) |

<Note>
  **캐시 동작**

  transcript는 15분간 캐시돼요. 같은 노트에 대한 후속 요청은 더 빨라요.
</Note>