yt_transcript_rs/

transcript.rs

use reqwest::Client;
use std::collections::HashMap;
use std::fmt;

use crate::errors::{CouldNotRetrieveTranscript, CouldNotRetrieveTranscriptReason};
use crate::fetched_transcript::FetchedTranscript;
use crate::innertube_client::InnerTubeClient;
use crate::models::TranslationLanguage;
use crate::transcript_parser::TranscriptParser;

/// # Transcript
///
/// Represents a YouTube transcript that can be fetched or translated.
///
/// This struct contains the metadata and access URLs for a transcript but not
/// the actual transcript text content. It serves as a handle to retrieve the
/// full transcript text when needed.
///
/// A `Transcript` object can represent:
/// - A native transcript in its original language
/// - A translatable transcript that can be converted to other languages
/// - A manually created transcript (more accurate, created by humans)
/// - An automatically generated transcript (created by YouTube's speech recognition)
///
/// ## Usage Example
///
/// ```rust,no_run
/// # use yt_transcript_rs::YouTubeTranscriptApi;
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let api = YouTubeTranscriptApi::new(None, None, None)?;
/// let transcript_list = api.list_transcripts("dQw4w9WgXcQ").await?;
///
/// // Find an English transcript
/// let transcript = transcript_list.find_transcript(&["en"])?;
///
/// // Check if it can be translated
/// if transcript.is_translatable() {
///     // Translate to Spanish
///     let spanish = transcript.translate("es")?;
///     
///     // Fetch the translated content
///     let client = reqwest::Client::new();
///     let fetched = spanish.fetch(&client, false).await?;
///     println!("Spanish transcript: {}", fetched.text());
/// }
///
/// // Or fetch the original transcript
/// let client = reqwest::Client::new();
/// let fetched = transcript.fetch(&client, false).await?;
/// println!("Original transcript: {}", fetched.text());
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct Transcript {
    /// The YouTube video ID this transcript belongs to
    pub video_id: String,

    /// URL to fetch the transcript content from YouTube
    pub url: String,

    /// Full human-readable language name (e.g., "English")
    pub language: String,

    /// Language code (e.g., "en", "en-US", "es")
    pub language_code: String,

    /// Whether this transcript was automatically generated by YouTube
    pub is_generated: bool,

    /// List of languages this transcript can be translated to
    pub translation_languages: Vec<TranslationLanguage>,

    /// Mapping of language codes to language names for available translations
    pub translation_languages_map: HashMap<String, String>,
}

impl Transcript {
    /// Creates a new transcript instance.
    ///
    /// This constructor creates a transcript object that can be used to fetch
    /// the actual transcript content or to generate translations.
    ///
    /// # Parameters
    ///
    /// * `video_id` - YouTube video ID
    /// * `url` - URL to fetch the transcript content
    /// * `language` - Human-readable language name (e.g., "English")
    /// * `language_code` - Language code (e.g., "en", "en-US")
    /// * `is_generated` - Whether this transcript was automatically generated
    /// * `translation_languages` - List of languages this transcript can be translated to
    ///
    /// # Returns
    ///
    /// A new `Transcript` instance
    ///
    /// # Example (internal usage)
    ///
    /// ```rust,no_run
    /// # use reqwest::Client;
    /// # use yt_transcript_rs::transcript::Transcript;
    /// # use yt_transcript_rs::models::TranslationLanguage;
    /// # fn example() {
    /// // Create a transcript for English
    /// let transcript = Transcript::new(
    ///     "dQw4w9WgXcQ".to_string(),
    ///     "https://www.youtube.com/api/timedtext?...".to_string(),
    ///     "English".to_string(),
    ///     "en".to_string(),
    ///     false, // Not automatically generated
    ///     vec![
    ///         TranslationLanguage {
    ///             language: "Spanish".to_string(),
    ///             language_code: "es".to_string()
    ///         }
    ///     ]
    /// );
    /// # }
    /// ```
    pub fn new(
        video_id: String,
        url: String,
        language: String,
        language_code: String,
        is_generated: bool,
        translation_languages: Vec<TranslationLanguage>,
    ) -> Self {
        let translation_languages_map = translation_languages
            .iter()
            .map(|lang| (lang.language_code.clone(), lang.language.clone()))
            .collect();

        Self {
            video_id,
            url,
            language,
            language_code,
            is_generated,
            translation_languages,
            translation_languages_map,
        }
    }

    /// Fetches the actual transcript content from YouTube.
    ///
    /// This method retrieves the transcript text and timing information from YouTube
    /// using YouTube's internal InnerTube API, which provides reliable access to
    /// transcript data even when YouTube updates their external API requirements.
    ///
    /// # Parameters
    ///
    /// * `client` - HTTP client for making requests to YouTube
    /// * `preserve_formatting` - Whether to preserve HTML formatting in the transcript
    ///   (e.g., bold, italic, etc.)
    ///
    /// # Returns
    ///
    /// * `Result<FetchedTranscript, CouldNotRetrieveTranscript>` - The fetched transcript or an error
    ///
    /// # Errors
    ///
    /// This method will return an error if:
    /// - The network request to YouTube fails
    /// - YouTube returns a non-OK status code
    /// - The transcript data cannot be parsed
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use reqwest::Client;
    /// # use yt_transcript_rs::YouTubeTranscriptApi;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = Client::new();
    /// let api = YouTubeTranscriptApi::new(None, None, None)?;
    /// let transcript_list = api.list_transcripts("dQw4w9WgXcQ").await?;
    /// let transcript = transcript_list.find_transcript(&["en"])?;
    ///
    /// // Fetch without preserving formatting
    /// let plain_transcript = transcript.fetch(&client, false).await?;
    ///
    /// // Fetch and preserve HTML formatting like <b>bold</b> text
    /// let formatted_transcript = transcript.fetch(&client, true).await?;
    ///
    /// // Access the full text
    /// println!("Transcript: {}", plain_transcript.text());
    ///
    /// // Or iterate through individual segments
    /// for segment in plain_transcript.parts() {
    ///     println!("[{:.1}s]: {}", segment.start, segment.text);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn fetch(
        &self,
        client: &Client,
        preserve_formatting: bool,
    ) -> Result<FetchedTranscript, CouldNotRetrieveTranscript> {
        // Use InnerTube API directly - this is now the only reliable method
        let innertube_client = InnerTubeClient::new(client.clone());

        // Get fresh transcript URLs from InnerTube API
        let data = innertube_client
            .get_transcript_list(&self.video_id)
            .await
            .map_err(|e| CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::YouTubeRequestFailed(
                    format!("InnerTube API failed: {}", e),
                )),
            })?;

        // Extract caption tracks from the InnerTube response
        let captions = data
            .get("captions")
            .ok_or_else(|| CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::YouTubeDataUnparsable(
                    "No captions found in InnerTube response".to_string(),
                )),
            })?;

        let player_captions_renderer =
            captions
                .get("playerCaptionsTracklistRenderer")
                .ok_or_else(|| CouldNotRetrieveTranscript {
                    video_id: self.video_id.clone(),
                    reason: Some(CouldNotRetrieveTranscriptReason::YouTubeDataUnparsable(
                        "No playerCaptionsTracklistRenderer found".to_string(),
                    )),
                })?;

        let caption_tracks = player_captions_renderer
            .get("captionTracks")
            .and_then(|ct| ct.as_array())
            .ok_or_else(|| CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::YouTubeDataUnparsable(
                    "No caption tracks found in InnerTube response".to_string(),
                )),
            })?;

        // Find the matching transcript URL for our language
        let mut matching_url = None;
        for track in caption_tracks {
            if let Some(language_code) = track.get("languageCode").and_then(|lc| lc.as_str()) {
                if language_code == self.language_code {
                    if let Some(base_url) = track.get("baseUrl").and_then(|url| url.as_str()) {
                        matching_url = Some(base_url.to_string());
                        break;
                    }
                }
            }
        }

        let transcript_url = matching_url.ok_or_else(|| CouldNotRetrieveTranscript {
            video_id: self.video_id.clone(),
            reason: Some(CouldNotRetrieveTranscriptReason::NoTranscriptFound {
                requested_language_codes: vec![self.language_code.clone()],
                transcript_data: crate::transcript_list::TranscriptList::new(
                    self.video_id.clone(),
                    HashMap::new(),
                    HashMap::new(),
                    vec![],
                ),
            }),
        })?;

        // Fetch transcript content using the fresh URL from InnerTube
        let response =
            client
                .get(&transcript_url)
                .send()
                .await
                .map_err(|e| CouldNotRetrieveTranscript {
                    video_id: self.video_id.clone(),
                    reason: Some(CouldNotRetrieveTranscriptReason::YouTubeRequestFailed(
                        format!("Failed to fetch transcript: {}", e),
                    )),
                })?;

        if response.status() != reqwest::StatusCode::OK {
            return Err(CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::YouTubeRequestFailed(
                    format!("YouTube returned status code {}", response.status()),
                )),
            });
        }

        let text = response
            .text()
            .await
            .map_err(|e| CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::YouTubeRequestFailed(
                    format!("Failed to read transcript response: {}", e),
                )),
            })?;

        if text.is_empty() {
            return Err(CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::YouTubeRequestFailed(
                    "YouTube returned empty transcript content. This may indicate additional restrictions or API changes.".to_string()
                )),
            });
        }

        let snippets = TranscriptParser::new(preserve_formatting)
            .parse(&text)
            .map_err(|e| CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::YouTubeDataUnparsable(
                    format!("Failed to parse transcript XML: {}", e),
                )),
            })?;

        Ok(FetchedTranscript {
            snippets,
            video_id: self.video_id.clone(),
            language: self.language.clone(),
            language_code: self.language_code.clone(),
            is_generated: self.is_generated,
        })
    }

    /// Checks if this transcript can be translated to other languages.
    ///
    /// This method determines whether YouTube offers translation capabilities
    /// for this transcript. Not all transcripts are translatable.
    ///
    /// # Returns
    ///
    /// * `bool` - `true` if this transcript can be translated, `false` otherwise
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use yt_transcript_rs::YouTubeTranscriptApi;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let api = YouTubeTranscriptApi::new(None, None, None)?;
    /// let transcript_list = api.list_transcripts("dQw4w9WgXcQ").await?;
    /// let transcript = transcript_list.find_transcript(&["en"])?;
    ///
    /// if transcript.is_translatable() {
    ///     println!("This transcript can be translated to other languages");
    ///     
    ///     // Available translation languages
    ///     for lang in &transcript.translation_languages {
    ///         println!("- {} ({})", lang.language, lang.language_code);
    ///     }
    /// } else {
    ///     println!("This transcript cannot be translated");
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn is_translatable(&self) -> bool {
        !self.translation_languages.is_empty()
    }

    /// Creates a translated version of this transcript in the specified language.
    ///
    /// This method creates a new `Transcript` instance representing the same content
    /// but translated to the requested language. Note that this doesn't actually perform
    /// the translation yet - the translation happens when you call `fetch()` on the
    /// returned transcript.
    ///
    /// # Parameters
    ///
    /// * `language_code` - The target language code to translate to (e.g., "es", "fr", "de")
    ///
    /// # Returns
    ///
    /// * `Result<Self, CouldNotRetrieveTranscript>` - A new transcript object representing
    ///   the translation, or an error
    ///
    /// # Errors
    ///
    /// This method will return an error if:
    /// - The transcript is not translatable
    /// - The requested language is not available for translation
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use reqwest::Client;
    /// # use yt_transcript_rs::YouTubeTranscriptApi;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = Client::new();
    /// let api = YouTubeTranscriptApi::new(None, None, None)?;
    /// let transcript_list = api.list_transcripts("dQw4w9WgXcQ").await?;
    /// let transcript = transcript_list.find_transcript(&["en"])?;
    ///
    /// // Create Spanish translation
    /// if transcript.is_translatable() {
    ///     // Translate to Spanish
    ///     let spanish_transcript = transcript.translate("es")?;
    ///     
    ///     // Fetch the translated content
    ///     let spanish_content = spanish_transcript.fetch(&client, false).await?;
    ///     println!("Spanish translation: {}", spanish_content.text());
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn translate(&self, language_code: &str) -> Result<Self, CouldNotRetrieveTranscript> {
        if !self.is_translatable() {
            return Err(CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::TranslationUnavailable(
                    "This transcript cannot be translated".to_string(),
                )),
            });
        }

        if !self.translation_languages_map.contains_key(language_code) {
            let available_langs = self
                .translation_languages
                .iter()
                .map(|l| format!("{} ({})", l.language, l.language_code))
                .collect::<Vec<_>>()
                .join(", ");

            return Err(CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(
                    CouldNotRetrieveTranscriptReason::TranslationLanguageUnavailable(format!(
                        "Translation to '{}' is not available. Available languages: {}",
                        language_code, available_langs
                    )),
                ),
            });
        }

        let language = self
            .translation_languages_map
            .get(language_code)
            .cloned()
            .unwrap();

        let translated_url = format!("{}&tlang={}", self.url, language_code);

        Ok(Self {
            video_id: self.video_id.clone(),
            url: translated_url,
            language,
            language_code: language_code.to_string(),
            is_generated: self.is_generated,
            translation_languages: self.translation_languages.clone(),
            translation_languages_map: self.translation_languages_map.clone(),
        })
    }

    /// Translates this transcript and fetches the result in a single operation.
    ///
    /// This convenience method combines the `translate` and `fetch` operations.
    ///
    /// # Parameters
    ///
    /// * `client` - HTTP client for making requests to YouTube
    /// * `language_code` - The target language code to translate to
    /// * `preserve_formatting` - Whether to preserve HTML formatting
    ///
    /// # Returns
    ///
    /// * `Result<FetchedTranscript, CouldNotRetrieveTranscript>` - The fetched translated transcript or an error
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use reqwest::Client;
    /// # use yt_transcript_rs::YouTubeTranscriptApi;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = Client::new();
    /// let api = YouTubeTranscriptApi::new(None, None, None)?;
    /// let transcript_list = api.list_transcripts("dQw4w9WgXcQ").await?;
    /// let transcript = transcript_list.find_transcript(&["en"])?;
    ///
    /// if transcript.is_translatable() {
    ///     // Translate to Spanish and fetch in one step
    ///     let spanish_content = transcript.translate_and_fetch(&client, "es", false).await?;
    ///     println!("Spanish translation: {}", spanish_content.text());
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn translate_and_fetch(
        &self,
        client: &Client,
        language_code: &str,
        preserve_formatting: bool,
    ) -> Result<FetchedTranscript, CouldNotRetrieveTranscript> {
        let translated = self.translate(language_code)?;
        translated.fetch(client, preserve_formatting).await
    }

    /// Returns the human-readable language name of this transcript.
    ///
    /// # Returns
    ///
    /// * `&str` - The language name (e.g., "English", "Español")
    pub fn language(&self) -> &str {
        &self.language
    }

    /// Returns the language code of this transcript.
    ///
    /// # Returns
    ///
    /// * `&str` - The language code (e.g., "en", "es", "fr-CA")
    pub fn language_code(&self) -> &str {
        &self.language_code
    }

    /// Checks if this transcript was automatically generated by YouTube.
    ///
    /// # Returns
    ///
    /// * `bool` - `true` if automatically generated, `false` if manually created
    pub fn is_generated(&self) -> bool {
        self.is_generated
    }
}

impl fmt::Display for Transcript {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let translation_desc = if self.is_translatable() {
            "[TRANSLATABLE]"
        } else {
            ""
        };
        write!(
            f,
            "{} ({}){}",
            self.language_code, self.language, translation_desc
        )
    }
}