> ## Documentation Index
> Fetch the complete documentation index at: https://docs.benzinga.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transcripts Stream
> 실시간 실적 발표 콜 발언을 말하는 즉시 문장 단위로 스트리밍합니다.
## 개요
실시간 실적 발표 콜 콜(transcript)에 구독하면 라이브 실적 발표 콜에서 발언되는 내용을 문장 단위로 바로 받아볼 수 있습니다. 실시간 transcript 뷰어와 분석 도구를 구축하기에 적합합니다.
### 주요 기능
* **실시간 전사**: 실적 발표 콜 중 발언 내용을 문장 단위로 실시간으로 받아보기
* **단어 단위 타이밍**: 각 문장에 단어별 타임스탬프와 신뢰도 점수가 포함
* **화자 식별**: 누가 말하고 있는지(임원, 애널리스트 등) 추적
* **상태 추적**: 전사가 진행 중인지 완료되었는지 모니터링
* **유연한 구독**: 특정 티커 또는 `*`를 사용해 모든 전사를 구독
* **모의 테스트**: 라이브 콜이 없을 때 모의 데이터를 사용해 통합을 테스트
### 사용 사례
* 실시간 실적 발표 콜 대본 뷰어 구축
* 실시간 자막 및 접근성 도구 구축
* 실적 발표 콜에 대한 실시간 감성 분석 수행
* 언급과 동시에 핵심 문구와 지표 추출
* 라이브 콜 중 특정 키워드나 주제에 대한 알림
* 정밀한 타이밍 데이터와 함께 전체 대본 아카이브
## 빠른 시작
위의 대화형 웹소켓 테스트 도구를 사용해 스트림에 실시간으로 연결하고 테스트하세요.
### 접속 URL
```
wss://api.benzinga.com/api/v1/transcripts/stream?token=YOUR_TOKEN
```
### 쿼리 매개변수
| 매개변수 | 필수 여부 | 설명 |
| ------- | ----- | ------------------------ |
| `token` | Yes | 사용자의 Benzinga 웹소켓 API 토큰 |
## 구독 명령
JSON 명령을 보내 구독을 제어합니다:
### 특정 티커 구독
```json theme={null}
{
"action": "subscribe",
"ticker": "AAPL"
}
```
### 모든 트랜스크립트 구독
```json theme={null}
{
"action": "subscribe",
"ticker": "*"
}
```
### 티커 구독 취소
```json theme={null}
{
"action": "unsubscribe",
"ticker": "AAPL"
}
```
### 활성화된 Transcript 목록
```json theme={null}
{
"action": "list"
}
```
### 연결 유지
```json theme={null}
{
"action": "ping"
}
```
### Mock 데이터로 테스트
라이브 트랜스크립트가 없을 때는 테스트를 위해 mock 모드를 사용하세요:
```json theme={null}
{
"action": "subscribe",
"ticker": "AAPL",
"mock": true
}
```
지원되는 모의 티커는 다음과 같습니다: `AAPL`, `MSFT`, `TSLA`
## 메시지 예제
```json theme={null}
{
"call_id": "call_123456",
"transcript_id": "550e8400-e29b-41d4-a716-446655440000",
"call_title": "Apple Inc. Q4 2024 Earnings Call",
"sentence": "Revenue for the quarter was 89.5 billion dollars.",
"start_time": "2024-01-15T16:30:15Z",
"end_time": "2024-01-15T16:30:19Z",
"symbol": "AAPL",
"exchange": "NASDAQ",
"name": "Apple Inc.",
"sequence": 42,
"status": "IN_PROGRESS",
"speaker": "Tim Cook, CEO",
"type": "LIVE",
"language": "en",
"confidence": 0.98,
"words": [
{
"text": "Revenue",
"confidence": 0.99,
"start": 0,
"end": 450
},
{
"text": "for",
"confidence": 0.98,
"start": 450,
"end": 600
}
],
"created_time": "2024-01-15T16:30:19Z"
}
```
### 주요 필드
| Field | Description |
| ------------------------- | ------------------------------------ |
| `sentence` | 발화된 전체 문장 텍스트 |
| `sequence` | 전사본에서 이 문장의 순서 (0, 1, 2...) |
| `speaker` | 발화자의 이름/식별자 |
| `status` | `IN_PROGRESS`(실시간) 또는 `COMPLETE`(완료) |
| `confidence` | 전체 인식 정확도 (0.0 - 1.0) |
| `words` | 각 단어별 타이밍 및 신뢰도가 포함된 배열 |
| `start_time` / `end_time` | 문장 타이밍을 나타내는 ISO 8601 타임스탬프 |
### Transcript 상태
| Status | Description |
| ------------- | ------------------------------------------ |
| `IN_PROGRESS` | 트랜스크립트가 현재 실시간으로 진행 중이며 업데이트가 계속 수신되고 있습니다 |
| `COMPLETE` | 트랜스크립트가 완료되었으며 더 이상의 업데이트는 발생하지 않습니다 |
## 단어 수준 데이터
각 문장에는 자세한 단어 수준 정보가 포함되어 있습니다.
```json theme={null}
{
"text": "Revenue",
"confidence": 0.99,
"start": 0,
"end": 450
}
```
* **text**: 단어 자체
* **confidence**: 인식 신뢰도 (0.0 - 1.0)
* **start/end**: 문장 시작 시점으로부터의 밀리초 단위 시간 오프셋
## 대화형 명령
| Command | Parameters | Description |
| ------------- | ---------- | ---------------------------------- |
| `subscribe` | `ticker` | 특정 티커의 콜 전 실적 발표 내용 업데이트를 구독합니다 |
| `unsubscribe` | `ticker` | 특정 티커의 업데이트 수신을 중지합니다 |
| `list` | - | 현재 활성/제공 중인 콜 전 실적 발표 내용 목록을 가져옵니다 |
| `subscribed` | - | 현재 사용자의 구독 목록을 가져옵니다 |
| `ping` | - | 연결을 유지합니다 (`pong`으로 응답) |
| `echo` | `message` | 에코 테스트를 수행합니다 (보낸 메시지로 응답) |
## 모범 사례
### 실시간 표시
* **버퍼 관리**: `sequence` 필드를 사용해 문장을 순서대로 표시합니다
* **화자 포맷팅**: `speaker` 값에 따라 다르게 표시합니다(임원 vs 애널리스트)
* **상태 표시기**: `IN_PROGRESS`와 `COMPLETE` 상태를 시각적으로 구분해 표시합니다
### 성능
* **와일드카드 주의**: `ticker: "*"`를 사용하면 모든 콜 텍스트에 구독되며, 데이터 양이 매우 많을 수 있습니다
* **대상 지정 구독**: 필요한 티커만 구독하여 대역폭 사용을 줄이십시오
* **하트비트**: 연결을 유지하기 위해 30\~60초마다 `ping`을 전송하십시오
### 데이터 품질
* **신뢰도 필터링**: 신뢰도 점수가 낮은 문장은 무시하거나 표시하도록 하는 방안을 고려합니다
* **단어 정확도**: 단어 단위 신뢰도를 사용해 신뢰도가 낮은 전사를 식별합니다
* **언어 처리**: 텍스트가 올바르게 렌더링되도록 `language` 필드를 확인합니다
### 테스트
* **Mock 모드**: 실제 호출이 없는 개발 환경에서는 `mock: true`를 사용하세요
* **에코 테스트**: 연결 및 메시지 처리 검증을 위해 `echo` action을 사용하세요
* **list 명령**: 현재 사용 가능한 항목을 확인하려면 `list`를 실행하세요
## 통합 예제
```javascript theme={null}
const ws = new WebSocket(
'wss://api.benzinga.com/api/v1/transcripts/stream?token=YOUR_TOKEN'
);
ws.onopen = () => {
// Apple 트랜스크립트 구독
ws.send(JSON.stringify({
action: 'subscribe',
ticker: 'AAPL'
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
// 발화자와 문장 표시
console.log(`[${data.sequence}] ${data.speaker}: ${data.sentence}`);
// 트랜스크립트 완료 여부 확인
if (data.status === 'COMPLETE') {
console.log('트랜스크립트 완료');
}
};
// 연결 유지
setInterval(() => {
ws.send(JSON.stringify({ action: 'ping' }));
}, 30000);
```
## 관련 문서
* [웹소켓 소개](../introduction) - 웹소켓 기본 개념과 연결 기초
* [인증](../authentication) - API 토큰을 발급받아 사용하는 방법
## AsyncAPI
````yaml asyncapi/transcripts-stream.yml transcripts
id: transcripts
title: Transcripts
description: Send action commands; receive real-time transcript updates
servers:
- id: production
protocol: wss
host: api.benzinga.com/api/v1/transcripts
bindings: []
variables: []
address: stream
parameters: []
bindings: []
operations:
- &ref_1
id: transcripts.publish
title: Transcripts.publish
description: Send commands to the server
type: receive
messages:
- &ref_3
id: publish
contentType: application/json
payload:
- name: publish
description: WebSocket command to interact with transcript stream
type: object
properties:
- name: action
type: string
description: Action to perform
enumValues:
- list
- subscribe
- unsubscribe
- subscribed
- echo
- ping
required: true
- name: ticker
type: string
description: Stock ticker symbol (e.g., AAPL) or '*' for all transcripts
required: false
- name: message
type: string
description: Optional message for echo testing
required: false
- name: mock
type: boolean
description: Optional boolean for mock testing when no live transcripts
required: false
headers: []
jsonPayloadSchema:
type: object
required:
- action
properties:
action:
type: string
enum:
- list
- subscribe
- unsubscribe
- subscribed
- echo
- ping
description: Action to perform
x-parser-schema-id:
ticker:
type: string
description: Stock ticker symbol (e.g., AAPL) or '*' for all transcripts
x-parser-schema-id:
message:
type: string
description: Optional message for echo testing
x-parser-schema-id:
mock:
type: boolean
description: Optional boolean for mock testing when no live transcripts
x-parser-schema-id:
x-parser-schema-id:
title: Publish
description: WebSocket command to interact with transcript stream
example: |-
{
"action": "list"
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: publish
- id: x-parser-message-name
value: ActionRequest
bindings: []
extensions: &ref_0
- id: x-parser-unique-object-id
value: transcripts
- &ref_2
id: transcripts.subscribe
title: Transcripts.subscribe
description: Receive real-time transcript data
type: send
messages:
- &ref_4
id: subscribe
contentType: application/json
payload:
- name: subscribe
description: Real-time transcript message
type: object
properties:
- name: call_id
type: string
description: Unique identifier for the earnings call
required: true
- name: transcript_id
type: string
description: Unique identifier for this transcript
required: true
- name: call_title
type: string
description: Title of the earnings call
required: false
- name: sentence
type: string
description: The spoken sentence text
required: true
- name: start_time
type: string
description: When this sentence started
required: false
- name: end_time
type: string
description: When this sentence ended
required: false
- name: symbol
type: string
description: Stock ticker symbol (e.g., AAPL)
required: true
- name: exchange
type: string
description: Exchange where security is listed
required: false
- name: isin
type: string
description: International Securities Identification Number
required: false
- name: cusip
type: string
description: CUSIP identifier
required: false
- name: name
type: string
description: Company name
required: false
- name: sequence
type: integer
description: Sequence number of this sentence in the transcript
required: true
- name: status
type: string
description: Status of the transcript
enumValues:
- IN_PROGRESS
- COMPLETE
required: true
- name: words
type: array
description: Individual words with timing and confidence
required: false
properties:
- name: confidence
type: number
description: Confidence score for word recognition
required: false
- name: start
type: integer
description: Start time offset in milliseconds
required: false
- name: end
type: integer
description: End time offset in milliseconds
required: false
- name: text
type: string
description: The word text
required: false
- name: confidence
type: number
description: Overall confidence score for the sentence
required: false
- name: speaker
type: string
description: Name or identifier of the speaker
required: false
- name: type
type: string
description: Type of transcript (LIVE for real-time)
enumValues:
- LIVE
required: false
- name: language
type: string
description: Language code (e.g., en, en-US)
required: false
- name: participants
type: array
description: List of call participants
required: false
properties:
- name: item
type: object
required: false
- name: created_time
type: string
description: When this transcript entry was created
required: false
headers: []
jsonPayloadSchema:
type: object
required:
- call_id
- transcript_id
- sentence
- symbol
- sequence
- status
properties:
call_id:
type: string
description: Unique identifier for the earnings call
x-parser-schema-id:
transcript_id:
type: string
format: uuid
description: Unique identifier for this transcript
x-parser-schema-id:
call_title:
type: string
description: Title of the earnings call
x-parser-schema-id:
sentence:
type: string
description: The spoken sentence text
x-parser-schema-id:
start_time:
type: string
format: date-time
description: When this sentence started
x-parser-schema-id:
end_time:
type: string
format: date-time
description: When this sentence ended
x-parser-schema-id:
symbol:
type: string
description: Stock ticker symbol (e.g., AAPL)
x-parser-schema-id:
exchange:
type: string
description: Exchange where security is listed
x-parser-schema-id:
isin:
type: string
description: International Securities Identification Number
x-parser-schema-id:
cusip:
type: string
description: CUSIP identifier
x-parser-schema-id:
name:
type: string
description: Company name
x-parser-schema-id:
sequence:
type: integer
description: Sequence number of this sentence in the transcript
x-parser-schema-id:
status:
type: string
enum:
- IN_PROGRESS
- COMPLETE
description: Status of the transcript
x-parser-schema-id:
words:
type: array
description: Individual words with timing and confidence
items:
type: object
properties:
confidence:
type: number
description: Confidence score for word recognition
x-parser-schema-id:
start:
type: integer
description: Start time offset in milliseconds
x-parser-schema-id:
end:
type: integer
description: End time offset in milliseconds
x-parser-schema-id:
text:
type: string
description: The word text
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
confidence:
type: number
description: Overall confidence score for the sentence
x-parser-schema-id:
speaker:
type: string
description: Name or identifier of the speaker
x-parser-schema-id:
type:
type: string
enum:
- LIVE
description: Type of transcript (LIVE for real-time)
x-parser-schema-id:
language:
type: string
description: Language code (e.g., en, en-US)
x-parser-schema-id:
participants:
type: array
nullable: true
description: List of call participants
items:
type: object
x-parser-schema-id:
x-parser-schema-id:
created_time:
type: string
format: date-time
description: When this transcript entry was created
x-parser-schema-id:
x-parser-schema-id:
title: Subscribe
description: Real-time transcript message
example: No examples found
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribe
- id: x-parser-message-name
value: TranscriptMessage
bindings: []
extensions: *ref_0
sendOperations:
- *ref_1
receiveOperations:
- *ref_2
sendMessages:
- *ref_3
receiveMessages:
- *ref_4
extensions:
- id: x-parser-unique-object-id
value: transcripts
securitySchemes:
- id: tokenAuth
name: token
type: httpApiKey
description: Benzinga WebSocket API token
in: query
extensions: []
````