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::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 fetched = spanish.fetch(false).await?;
///     println!("Spanish transcript: {}", fetched.text());
/// }
///
/// // Or fetch the original transcript
/// let fetched = transcript.fetch(false).await?;
/// println!("Original transcript: {}", fetched.text());
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct Transcript {
    /// HTTP client for making requests to YouTube
    pub client: Client,

    /// 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
    ///
    /// * `client` - HTTP client for making requests to YouTube
    /// * `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() {
    /// let client = Client::new();
    ///
    /// // Create a transcript for English
    /// let transcript = Transcript::new(
    ///     client,
    ///     "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(
        client: Client,
        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 {
            client,
            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
    /// and returns it as a structured `FetchedTranscript` object.
    ///
    /// # Parameters
    ///
    /// * `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 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"])?;
    ///
    /// // Fetch without preserving formatting
    /// let plain_transcript = transcript.fetch(false).await?;
    ///
    /// // Fetch and preserve HTML formatting like <b>bold</b> text
    /// let formatted_transcript = transcript.fetch(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,
        preserve_formatting: bool,
    ) -> Result<FetchedTranscript, CouldNotRetrieveTranscript> {
        let response =
            self.client
                .get(&self.url)
                .send()
                .await
                .map_err(|e| CouldNotRetrieveTranscript {
                    video_id: self.video_id.clone(),
                    reason: Some(CouldNotRetrieveTranscriptReason::YouTubeRequestFailed(
                        e.to_string(),
                    )),
                })?;

        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(
                    e.to_string(),
                )),
            })?;

        let snippets = TranscriptParser::new(preserve_formatting)
            .parse(&text.clone())
            .map_err(|_| CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::YouTubeDataUnparsable),
            })?;

        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 language code to translate to (e.g., "es" for Spanish)
    ///
    /// # 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 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"])?;
    ///
    /// // Create Spanish translation
    /// if transcript.is_translatable() {
    ///     let spanish = transcript.translate("es")?;
    ///     
    ///     // Now fetch the Spanish translation
    ///     let spanish_content = spanish.fetch(false).await?;
    ///     println!("Spanish: {}", spanish_content.text());
    ///     
    ///     // Create Japanese translation
    ///     let japanese = transcript.translate("ja")?;
    ///     let japanese_content = japanese.fetch(false).await?;
    ///     println!("Japanese: {}", japanese_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::NotTranslatable),
            });
        }

        if !self.translation_languages_map.contains_key(language_code) {
            return Err(CouldNotRetrieveTranscript {
                video_id: self.video_id.clone(),
                reason: Some(CouldNotRetrieveTranscriptReason::TranslationLanguageNotAvailable),
            });
        }

        let language = self
            .translation_languages_map
            .get(language_code)
            .unwrap()
            .clone();
        let url = format!("{}&tlang={}", self.url, language_code);

        Ok(Transcript::new(
            self.client.clone(),
            self.video_id.clone(),
            url,
            language,
            language_code.to_string(),
            true,
            vec![],
        ))
    }

    /// Returns the full 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
        )
    }
}