yttranscript

package module
v0.0.0-...-0ed3975 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 28, 2026 License: BSD-2-Clause Imports: 11 Imported by: 0

README

yt-transcript

A Go library and CLI tool for fetching and processing YouTube video transcripts.

This is effectively a wrapper around a github.com/horiagug/youtube-transcript-api-go, with the sole focus on returning text that is immediately useful, as youtube's transcript data is chunked in a way that make it challenging to work with as a full text document.

Features

  • Fetch YouTube video transcripts by video ID or URL
  • Support for multiple languages
  • Process transcripts into readable "smooshed" text with time-indexed offsets
  • Clean and idiomatic Go API
  • CLI tool for quick transcript retrieval

Installation

As a Library
go get github.com/paulstuart/yt-transcript
As a CLI Tool
go install github.com/paulstuart/yt-transcript/cmd/yttranscript@latest

Usage

Library Usage
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/paulstuart/yt-transcript"
)

func main() {
    // Create a new client
    client := yttranscript.NewClient()

    // Fetch transcript (supports video ID or full URL)
    result, err := client.FetchTranscript("dQw4w9WgXcQ", &yttranscript.TranscriptConfig{
        Lang: "en",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Smooshed.Text)
}
CLI Usage

Fetch a transcript in plain text format:

yttranscript -video dQw4w9WgXcQ

Fetch with a different language:

yttranscript -video dQw4w9WgXcQ -lang es

Get smooshed text output:

yttranscript -video dQw4w9WgXcQ -smoosh

Output as JSON:

yttranscript -video dQw4w9WgXcQ -format json

Smooshed output as JSON:

yttranscript -video dQw4w9WgXcQ -smoosh -format json

API Reference

Client
NewClient() *Client

Creates a new YouTube transcript client.

FetchTranscript(videoID string, config *TranscriptConfig) (*TranscriptResult, error)

Fetches the transcript for a YouTube video. The videoID parameter accepts:

  • Plain video IDs: dQw4w9WgXcQ
  • Full URLs: https://www.youtube.com/watch?v=dQw4w9WgXcQ
  • Short URLs: https://youtu.be/dQw4w9WgXcQ
ProcessTranscript
ProcessTranscript(ctx context.Context, channelID, videoID string, transcript *Transcript) (*Smooshed, error)

Processes a raw transcript into a "smooshed" text format with an index for time-based navigation. The smooshed format:

  • Combines transcript chunks into readable paragraphs
  • Maintains a timestamp index for seeking to specific times
  • Provides offset information for each text segment
Types
TranscriptConfig
  • Lang string - Language code (e.g., "en", "es", "fr")
TranscriptResult
  • VideoID string - YouTube video ID
  • VideoTitle string - Video title
  • Transcripts []TranscriptResponse - Transcript segments
TranscriptResponse
  • Text string - Transcript text
  • Duration float64 - Segment duration in seconds
  • Offset float64 - Start time in seconds
  • Lang string - Language code
Smooshed
  • VideoId string - YouTube video ID
  • Channel string - Channel ID
  • Text string - Combined readable text
  • Index []IndexEntry - Time-based index

Testing

Run all tests:

go test ./...

Run tests with integration tests (requires internet):

go test -v ./...

Run only unit tests (skip integration):

go test -v -short ./...

License

See LICENSE file for details.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ParagraphGap = 3.0 // seconds to consider a gap in transcript as a new paragraph

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides methods to fetch YouTube transcripts.

func NewClient 

func NewClient(timeoutSeconds int) *Client

NewClient creates a new YouTube transcript client. timeoutSeconds is applied per-request.

func (*Client) FetchRawTranscript 

func (c *Client) FetchRawTranscript(videoID string, config *TranscriptConfig) (*TranscriptRaw, error)

FetchRawTranscript fetches the raw transcript for a YouTube video. videoID may be a full URL or an 11-character video ID. config may be nil to use defaults (English, first available).

func (*Client) FetchTranscript 

func (c *Client) FetchTranscript(videoID string, config *TranscriptConfig) (*TranscriptResult, error)

FetchTranscript fetches and smooshes the transcript for a YouTube video.

type IndexEntry 

type IndexEntry struct {
	// Timestamp is the start time in seconds for this segment
	Timestamp float64 `json:"timestamp"`
	// Offset is the byte offset into the smooshed text at the Timestamp
	Offset int `json:"offset"`
}

IndexEntry represents a mapping from smooshed text offset to timestamp

type Smooshed 

type Smooshed struct {
	Text    string       `json:"text"`
	Indexes []IndexEntry `json:"indexes"`
}

Smooshed represents the transcript text as a string and includes indexed entries This data is the whole point of this project -- to retrieve a plain text transcript of a youtube video

func ProcessTranscript 

func ProcessTranscript(transcript *TranscriptRaw) (*Smooshed, error)

ProcessTranscript converts Youtube's chunky transcript into a smooshed text version with an index.

type TranscriptConfig 

type TranscriptConfig struct {
	// Lang specifies the language code for the transcript (e.g., "en" for English)
	// If empty, the first available language will be used
	Lang string
	// TimeoutSeconds specifies the timeout for fetching the transcript in seconds
	TimeoutSeconds int
}

TranscriptConfig holds configuration for fetching transcripts

type TranscriptEntry 

type TranscriptEntry struct {
	Text     string
	Start    float64 // seconds
	Duration float64 // seconds
}

TranscriptEntry represents a single transcript segment

type TranscriptInfo 

type TranscriptInfo struct {
	VideoID        string
	VideoTitle     string
	Language       string
	LanguageCode   string
	IsGenerated    bool
	IsTranslatable bool
}

TranscriptInfo represents the metadata comprising TranscriptRaw

func GetInfo 

func GetInfo(transcript *TranscriptRaw) *TranscriptInfo

GetInfo extracts TranscriptInfo from a TranscriptRaw

type TranscriptLine 

type TranscriptLine struct {
	Text     string  `json:"text"`
	Start    float64 `json:"start"`
	Duration float64 `json:"duration"`
}

TranscriptLine is a single timed segment of a transcript.

type TranscriptRaw 

type TranscriptRaw struct {
	VideoID        string
	VideoTitle     string
	Language       string
	LanguageCode   string
	IsGenerated    bool
	IsTranslatable bool
	Lines          []TranscriptLine
}

TranscriptRaw is the raw transcript data for a video.

type TranscriptResult 

type TranscriptResult struct {
	Info     *TranscriptInfo
	Smooshed *Smooshed
}

TranscriptResult contains the complete transcript and video metadata

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.