Podcast Transcription Workflow via Get笔记 API: Technical Implementation Guide

The transcription pipeline orchestrates three sequential Get笔记 API calls—creating a link note, polling for task completion, and retrieving the full transcript—while automatically managing JWT refresh and temporary file persistence.

The joeseesun/qiaomu-anything-to-notebooklm repository implements a robust podcast transcription workflow that converts audio content from platforms like 小宇宙, 喜马拉雅, and Bilibili into structured text using the Get笔记 API. This technical pipeline bridges spoken content and NotebookLM-compatible formats, enabling automated deep analysis and quiz generation. Understanding the exact sequence of API interactions and credential management is essential for developers integrating similar transcription capabilities.

Prerequisites and Authentication

Before invoking any transcription logic, the script validates two mandatory environment variables: GETNOTE_API_KEY and GETNOTE_CLIENT_ID. These credentials are verified at startup in scripts/get_podcast_transcript.py (lines 15-19). Without proper authentication, the API client cannot establish the JWT session required for subsequent requests, and the process exits immediately with an error message.

export GETNOTE_API_KEY="your_api_key"
export GETNOTE_CLIENT_ID="your_client_id"

The Four-Stage Transcription Pipeline

Stage 1: Input Detection and Routing

The workflow initiates in main.py where the detect_input_type function (lines 23-24) identifies podcast URLs from supported platforms. When the system detects a valid podcast link, execution routes to the dedicated transcription routine, passing the URL to the helper script.

Stage 2: Creating the Link Note Task

The script sends a POST request to /open/api/v1/resource/note/save to initiate the background transcription job. This endpoint accepts the podcast URL and returns a unique task_id that serves as the reference for tracking progress across subsequent API calls.

Stage 3: Polling for Completion

Transcription processing is asynchronous. The implementation polls the endpoint /open/api/v1/resource/note/task/progress every 30 seconds for up to 40 attempts (lines 115-124 in get_podcast_transcript.py). This polling loop monitors the task status until the response returns success, at which point the associated note_id becomes available for content retrieval.

Stage 4: Retrieving and Persisting the Transcript

Using the retrieved note_id, the script queries https://get-notes.luojilab.com/voicenotes/web/notes/<note_id>/links/detail to fetch the complete JSON payload (lines 132-138). This response contains the transcript content, along with metadata fields including title and web_title. The text is sanitized and saved to a temporary .txt file with a filename derived safely from the content title (lines 144-152).

Integration with the Main Processing Flow

After scripts/get_podcast_transcript.py executes, it prints a JSON summary to stdout containing txt_path, title, content_length, note_id, and source_url. The main entry point in main.py (lines 65-73) captures this output, parses the JSON structure, and either uploads the transcript text directly to NotebookLM or triggers a deep-analysis pass for downstream report generation.

Command-Line Usage

You can trigger the complete workflow through the main interface:

python3 main.py https://xiaoyuzhoufm.com/episode/12345

For debugging or standalone transcription without NotebookLM integration, invoke the helper script directly:

python3 scripts/get_podcast_transcript.py https://xiaoyuzhoufm.com/episode/12345

Sample JSON output from the transcription script:

{
  "txt_path": "/tmp/podcast_这期播客_abcdef.txt",
  "title": "这期播客 – AI 时代的挑战",
  "content_length": 12873,
  "note_id": "987654321",
  "source_url": "https://xiaoyuzhoufm.com/episode/12345"
}

Summary

• The workflow requires GETNOTE_API_KEY and GETNOTE_CLIENT_ID environment variables configured before execution.
• Three distinct API endpoints orchestrate the transcription: task creation (/note/save), progress polling (/task/progress), and content retrieval (/links/detail).
• The polling mechanism executes every 30 seconds with a maximum of 40 attempts, supporting transcription jobs lasting up to 20 minutes.
• Completed transcripts are persisted as temporary .txt files with safe filenames before being passed to the NotebookLM integration layer.

Frequently Asked Questions

What podcast platforms are supported by this Get笔记 API workflow?

The implementation specifically handles URLs from 小宇宙 (Xiaoyuzhou), 喜马拉雅 (Ximalaya), and Bilibili (B站). The detect_input_type function in main.py recognizes these domain patterns and routes them to the Get笔记 transcription pipeline, while other input types are processed through different handlers.

How does the script handle JWT token expiration during transcription?

The get_podcast_transcript.py script implements automatic JWT refresh logic that monitors token validity during the polling phase. If authentication expires while waiting for transcription completion or during content retrieval, the system transparently refreshes credentials without interrupting the workflow or losing the task context.

What is the maximum wait time for a podcast transcription to complete?

With a polling interval of 30 seconds and a maximum of 40 retry attempts, the system will wait up to 20 minutes for the Get笔记 service to complete transcription before timing out. This accommodates lengthy podcast episodes while preventing infinite loops.

Where are the temporary transcript files stored?

The script generates safe filenames based on the podcast title and saves them to the system's temporary directory (typically /tmp/ on Unix systems or %TEMP% on Windows). The exact file path is returned in the JSON output's txt_path field, and files persist until the system's temporary cleanup routine removes them.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}