# tuber [![R-CMD-check](https://github.com/gojiplus/tuber/actions/workflows/R-CMD-check.yml/badge.svg)](https://github.com/gojiplus/tuber/actions/workflows/R-CMD-check.yml) [![CRAN status](https://www.r-pkg.org/badges/version/tuber)](https://cran.r-project.org/package=tuber) [![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/tuber)](https://cran.r-project.org/package=tuber) [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://gojiplus.github.io/tuber/) `tuber` is an R client for the YouTube Data API and selected YouTube Live Streaming API endpoints. It searches public YouTube data, retrieves channels, videos, playlists, comments, and captions, and supports common authenticated operations such as uploads, comment moderation, and playlist changes. The package does not wrap every YouTube endpoint. Run [`vignette("api-conventions", package = "tuber")`](https://gojiplus.github.io/tuber/articles/api-conventions.md) for the supported resources and known omissions. ## Installation Install the CRAN release: ``` r install.packages("tuber") ``` Install the development version from GitHub: ``` r # install.packages("pak") pak::pak("gojiplus/tuber") ``` ## Authentication Public read functions use an API key by default. Create a key in Google Cloud, enable the YouTube Data API v3 for that project, and set the key for the current R session: ``` r yt_set_key("YOUR_YOUTUBE_API_KEY") ``` OAuth is required for private account data and every operation that changes YouTube data. Create a desktop OAuth client in Google Cloud, then authenticate in the system browser: ``` r yt_oauth("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET") ``` [`yt_oauth()`](https://gojiplus.github.io/tuber/reference/yt_oauth.md) stores its token in the user’s R cache directory by default. Pass an explicit `token` path if you need a different location. ## Examples Search for videos: ``` r videos <- yt_search("Barack Obama", max_results = 25) ``` Retrieve fixed, snake-case video statistics: ``` r stats <- get_video_stats("N708P-A45D0") ``` List a channel’s playlists and the videos in one playlist: ``` r playlists <- list_playlists(channel_id = "UCMtFAi84ehTSYSE9XoHefig") items <- list_playlist_items( playlist_id = playlists$playlist_id[[1]], max_results = 100 ) ``` Collect top-level comments and all replies: ``` r comments <- get_all_comments("a-UQz7fqR3w", max_results = 500) ``` List and download caption tracks for a video owned by the authenticated account: ``` r tracks <- list_captions("yJXTXN4xrI8") caption <- download_caption(tracks$caption_id[[1]], as_raw = FALSE) ``` ## API conventions - `list_*()` functions mirror YouTube list endpoints and return a data frame by default. Use `simplify = FALSE` to keep the collected API response. - `get_*()` functions return a derived, enriched, or singular result. - Plural ID arguments accept vectors. Singular ID arguments accept one value. - `max_results` is the total result limit, even when the function makes several paginated requests. - Fixed simplified schemas use snake-case column names. The columns returned by [`get_video_details()`](https://gojiplus.github.io/tuber/reference/get_video_details.md) depend on `part` and retain YouTube’s field names. - Public reads default to `auth = "key"`. Functions that can use either form of authentication accept `auth = "key"` or `auth = "token"`. OAuth-only functions do not expose an `auth` argument. ## License `tuber` is released under the [MIT License](https://gojiplus.github.io/tuber/LICENSE). # Package index ## Package Documentation Overall package documentation - [`tuber`](https://gojiplus.github.io/tuber/reference/tuber.md) : tuber provides access to the YouTube API V3. ## Authentication Functions for authentication with the YouTube API - [`yt_oauth()`](https://gojiplus.github.io/tuber/reference/yt_oauth.md) : Set up Authorization - [`yt_token()`](https://gojiplus.github.io/tuber/reference/yt_token.md) [`yt_authorized()`](https://gojiplus.github.io/tuber/reference/yt_token.md) [`yt_check_token()`](https://gojiplus.github.io/tuber/reference/yt_token.md) : Check if authentication token is in options - [`yt_get_key()`](https://gojiplus.github.io/tuber/reference/yt_key.md) [`yt_set_key()`](https://gojiplus.github.io/tuber/reference/yt_key.md) : Manage YouTube API key ## Channel Functions Functions for working with YouTube channels - [`get_channel_details()`](https://gojiplus.github.io/tuber/reference/get_channel_details.md) [`get_my_channel()`](https://gojiplus.github.io/tuber/reference/get_channel_details.md) : Get Channel Details - [`list_subscriptions()`](https://gojiplus.github.io/tuber/reference/list_subscriptions.md) : List Subscriptions - [`list_channel_sections()`](https://gojiplus.github.io/tuber/reference/list_channel_sections.md) : List Channel Sections - [`delete_channel_section()`](https://gojiplus.github.io/tuber/reference/delete_channel_section.md) : Delete a Channel Section - [`list_channel_activities()`](https://gojiplus.github.io/tuber/reference/list_channel_activities.md) : List Channel Activities - [`list_channel_videos()`](https://gojiplus.github.io/tuber/reference/list_channel_videos.md) : Returns List of Requested Channel Videos - [`get_all_channel_video_stats()`](https://gojiplus.github.io/tuber/reference/get_all_channel_video_stats.md) : Get statistics on all the videos in a Channel ## Video Functions Functions for working with YouTube videos - [`get_video_stats()`](https://gojiplus.github.io/tuber/reference/get_video_stats.md) : Get Video Statistics - [`get_video_details()`](https://gojiplus.github.io/tuber/reference/get_video_details.md) : Get Video Details - [`list_popular_videos()`](https://gojiplus.github.io/tuber/reference/list_popular_videos.md) : List Most-Popular Videos - [`list_my_videos()`](https://gojiplus.github.io/tuber/reference/list_my_videos.md) : List My Videos - [`upload_video()`](https://gojiplus.github.io/tuber/reference/upload_video.md) : Upload Video to Youtube - [`update_video_metadata()`](https://gojiplus.github.io/tuber/reference/update_video_metadata.md) : Update Video Metadata - [`delete_video()`](https://gojiplus.github.io/tuber/reference/delete_video.md) : Delete a Video ## Playlist Functions Functions for working with playlists - [`list_playlists()`](https://gojiplus.github.io/tuber/reference/list_playlists.md) : List Playlists - [`list_playlist_items()`](https://gojiplus.github.io/tuber/reference/list_playlist_items.md) : List Playlist Items - [`get_playlist_item_ids()`](https://gojiplus.github.io/tuber/reference/get_playlist_item_ids.md) : Get Playlist-Item IDs - [`get_playlist_video_ids()`](https://gojiplus.github.io/tuber/reference/get_playlist_video_ids.md) : Get Video IDs from a Playlist - [`create_playlist()`](https://gojiplus.github.io/tuber/reference/create_playlist.md) : Create New Playlist - [`add_video_to_playlist()`](https://gojiplus.github.io/tuber/reference/add_video_to_playlist.md) : Add Video to Playlist - [`change_playlist_title()`](https://gojiplus.github.io/tuber/reference/change_playlist_title.md) : Change a Playlist Title - [`delete_playlist_item()`](https://gojiplus.github.io/tuber/reference/delete_playlist_item.md) : Delete a Playlist Item - [`delete_playlist()`](https://gojiplus.github.io/tuber/reference/delete_playlist.md) : Delete a Playlist ## Caption Functions Functions for working with captions - [`download_caption()`](https://gojiplus.github.io/tuber/reference/download_caption.md) : Download a Caption Track - [`list_captions()`](https://gojiplus.github.io/tuber/reference/list_captions.md) : List Caption Tracks - [`upload_caption()`](https://gojiplus.github.io/tuber/reference/upload_caption.md) : Upload a Caption Track - [`delete_caption()`](https://gojiplus.github.io/tuber/reference/delete_caption.md) : Delete a Caption Track - [`read_sbv()`](https://gojiplus.github.io/tuber/reference/read_sbv.md) : Read SBV file ## Comment Functions Functions for working with comments and moderation - [`list_comment_threads()`](https://gojiplus.github.io/tuber/reference/list_comment_threads.md) : List Comment Threads - [`list_comments()`](https://gojiplus.github.io/tuber/reference/list_comments.md) : List Comments or Replies - [`get_all_comments()`](https://gojiplus.github.io/tuber/reference/get_all_comments.md) : Get All Video Comments, Including Replies - [`post_comment()`](https://gojiplus.github.io/tuber/reference/post_comment.md) : Post a Top-Level Comment - [`reply_to_comment()`](https://gojiplus.github.io/tuber/reference/reply_to_comment.md) : Reply to a Comment - [`set_comment_moderation_status()`](https://gojiplus.github.io/tuber/reference/set_comment_moderation_status.md) : Set Comment Moderation Status - [`delete_comment()`](https://gojiplus.github.io/tuber/reference/delete_comment.md) : Delete a Comment ## Monetization & Engagement Functions for Super Chats, Memberships, and Live Interaction - [`list_super_chat_events()`](https://gojiplus.github.io/tuber/reference/list_super_chat_events.md) : List Super Chat Events - [`list_live_chat_messages()`](https://gojiplus.github.io/tuber/reference/list_live_chat_messages.md) : List Live Chat Messages - [`list_live_broadcasts()`](https://gojiplus.github.io/tuber/reference/list_live_broadcasts.md) : List live broadcasts - [`list_channel_members()`](https://gojiplus.github.io/tuber/reference/list_channel_members.md) : List Channel Members ## Branding & Media Functions for thumbnails and channel branding - [`set_video_thumbnail()`](https://gojiplus.github.io/tuber/reference/set_video_thumbnail.md) : Set Video Thumbnail - [`insert_channel_banner()`](https://gojiplus.github.io/tuber/reference/insert_channel_banner.md) : Insert Channel Banner ## Search Functions Functions for searching YouTube - [`yt_search()`](https://gojiplus.github.io/tuber/reference/yt_search.md) : Search YouTube - [`search_short_videos()`](https://gojiplus.github.io/tuber/reference/search_short_videos.md) : Search for videos shorter than four minutes ## Additional Resources Functions for getting YouTube metadata - [`list_languages()`](https://gojiplus.github.io/tuber/reference/list_languages.md) : List Supported Languages - [`list_regions()`](https://gojiplus.github.io/tuber/reference/list_regions.md) : List Supported Content Regions - [`list_video_categories()`](https://gojiplus.github.io/tuber/reference/list_video_categories.md) : List Video Categories - [`list_abuse_report_reasons()`](https://gojiplus.github.io/tuber/reference/list_abuse_report_reasons.md) : List Video-Abuse Report Reasons ## Quota Management Functions for tracking and managing YouTube API quota usage - [`quota_management`](https://gojiplus.github.io/tuber/reference/quota_management.md) : YouTube API Quota Management - [`yt_get_quota_usage()`](https://gojiplus.github.io/tuber/reference/yt_get_quota_usage.md) : Get Current Quota Usage - [`yt_reset_quota()`](https://gojiplus.github.io/tuber/reference/yt_reset_quota.md) : Reset Quota Counter - [`yt_set_quota_limit()`](https://gojiplus.github.io/tuber/reference/yt_set_quota_limit.md) : Set Quota Limit ## Bulk Analysis Functions for processing multiple items efficiently - [`bulk_video_analysis()`](https://gojiplus.github.io/tuber/reference/bulk_video_analysis.md) : Bulk video performance analysis ## Analysis Helpers Higher-level analyses built from YouTube resources - [`analyze_channel()`](https://gojiplus.github.io/tuber/reference/analyze_channel.md) : Comprehensive channel analysis - [`analyze_trends()`](https://gojiplus.github.io/tuber/reference/analyze_trends.md) : Trending analysis for search terms - [`compare_channels()`](https://gojiplus.github.io/tuber/reference/compare_channels.md) : Compare multiple channels - [`get_video_broadcast_timing()`](https://gojiplus.github.io/tuber/reference/get_video_broadcast_timing.md) : Get video live-broadcast timing ## Unicode & Emoji Utilities Functions for handling emojis and Unicode in YouTube text - [`count_emojis()`](https://gojiplus.github.io/tuber/reference/count_emojis.md) : Count emojis in text - [`extract_emojis()`](https://gojiplus.github.io/tuber/reference/extract_emojis.md) : Extract emojis from text - [`has_emoji()`](https://gojiplus.github.io/tuber/reference/has_emoji.md) : Detect emojis in text - [`remove_emojis()`](https://gojiplus.github.io/tuber/reference/remove_emojis.md) : Remove emojis from text - [`replace_emojis()`](https://gojiplus.github.io/tuber/reference/replace_emojis.md) : Replace emojis in text ## Caching & Performance Functions for caching and performance optimization - [`tuber_cache_config()`](https://gojiplus.github.io/tuber/reference/tuber_cache_config.md) : Configure caching settings - [`tuber_cache_clear()`](https://gojiplus.github.io/tuber/reference/tuber_cache_clear.md) : Clear cache entries - [`tuber_cache_info()`](https://gojiplus.github.io/tuber/reference/tuber_cache_info.md) : Get current cache configuration - [`get_video_thumbnails()`](https://gojiplus.github.io/tuber/reference/get_video_thumbnails.md) : Get video thumbnails information - [`with_retry()`](https://gojiplus.github.io/tuber/reference/with_retry.md) : Exponential backoff retry logic for API calls ## Utility Functions Additional utility functions and information - [`tuber_info()`](https://gojiplus.github.io/tuber/reference/tuber_info.md) : Display tuber function metadata ## Documentation Topics Package documentation and function groups - [`extended-endpoints`](https://gojiplus.github.io/tuber/reference/extended-endpoints.md) : Extended YouTube API Endpoints - [`helper-functions`](https://gojiplus.github.io/tuber/reference/helper-functions.md) : Helper Functions for Common YouTube Analysis Tasks - [`caching`](https://gojiplus.github.io/tuber/reference/caching.md) : Response Caching for YouTube API - [`error-handling`](https://gojiplus.github.io/tuber/reference/error-handling.md) : Tuber Error Handling Utilities # Articles ### All vignettes - [API conventions and coverage](https://gojiplus.github.io/tuber/articles/api-conventions.md): - [Batch Processing & Quota Management](https://gojiplus.github.io/tuber/articles/batch-processing-quota.md): - [Emoji Analysis in YouTube Comments](https://gojiplus.github.io/tuber/articles/emoji-analysis.md): - [Handling Emojis and Unicode in YouTube Data](https://gojiplus.github.io/tuber/articles/emoji-handling.md): - [Troubleshooting Common Issues](https://gojiplus.github.io/tuber/articles/troubleshooting.md): - [Using tuber](https://gojiplus.github.io/tuber/articles/tuber-ex.md):