youtube_live_video

This module provides a block that displays the current YouTube live stream from a specified channel. If no stream is live, it can fall back to showing the most recent completed broadcast.

REQUIREMENTS

Drupal 10 or 11
A YouTube Data API v3 key.
A YouTube Channel ID.
(Optional) The Key module for secure API key storage.

INSTALLATION

Install as you would normally install a contributed Drupal module. Visit: https://www.drupal.org/node/1897420 for further information.

CONFIGURATION

Navigate to the Structure > Block layout page (/admin/structure/block).
Place a new YouTube Live Video block in the desired region.
Configure the block by entering the YouTube Channel ID.
Save the block.

Caching Strategies

To minimize API calls while maintaining responsiveness, this module provides several caching strategies. You can select a strategy within the block configuration:

1. Fixed Cache Duration

This is a general-purpose strategy that uses a two-tiered caching mechanism:

Long TTL: The standard cache duration.
Refresh Window: After the long TTL expires, the module enters a "refresh window" where it polls the API more frequently using a Short TTL to check for new content. If the content has not changed after the window expires, it reverts to the Long TTL.

2. Scheduled Window

Ideal for recurring events (like church services) where you know exactly when a live stream is likely to start.

How it works:

Outside the Window: The module uses a long cache duration until the next window begins, minimizing API usage.
Inside the Window: The module polls more frequently (using a Short TTL). Once new content is detected (e.g., the stream starts), it locks in that content until the next scheduled window begins.
Flexibility: Supports daily, weekly (on a specific day), or specific days of the week, with multiple time windows per day.

Best Practice Usage Pattern:

To ensure the block transitions to "LIVE" quickly and also reverts to the latest video quickly once the stream ends, it is recommended to use two windows:

Start Window: Set the start time to the beginning of your event. Set the duration to end about 5 minutes before you expect the stream to finish. This ensures the API is polled frequently when the event starts.
End Window: Set the start time to your expected end time with a shorter duration (e.g., 15-20 minutes). This forces the module to poll the API again at the end of your event to detect when the stream has concluded and update the block accordingly.

Support development on this module

A lot of hard work and dedication has gone into developing this module. If you find it helpful and would like to support ongoing development, consider buying me a coffee! Your support helps ensure that I can continue enhancing and maintaining this module for everyone. Thank you for your generosity!

Architecture

This module implements the Signed Configuration AJAX Pattern to solve the "Page Cache Paradox" (where static page caching prevents dynamic blocks from updating for anonymous users).

Block (YouTubeLiveVideoBlock): Renders a secure placeholder. It generates a set of configuration parameters (Channel ID, Strategy) signed with a cryptographic HMAC to prevent tampering.
Controller (YouTubeLiveVideoController): A stateless endpoint that validates the cryptographic signature and renders the video player.
Service (YouTubeVideoFetcher): Handles the logic of querying the YouTube API.
Strategy (CacheStrategyInterface): Determines how long the API result should be cached.
JavaScript (youtube-live-video.js): A lightweight loader that fetches the signed URL and injects the content into the placeholder.

Maintenance and Testing

The module includes a comprehensive suite of Unit and Kernel tests covering caching logic, API integration, and configuration forms.

Running Tests

To run the tests, use PHPUnit pointing to the module's configuration file.

From the host (via Podman):

phpunit -c web/modules/custom/youtube_live_video/phpunit.xml.dist \
web/modules/custom/youtube_live_video

Generating Coverage Reports

You can generate a text-based coverage report to see testing gaps:

phpunit -c web/modules/custom/youtube_live_video/phpunit.xml.dist \
web/modules/custom/youtube_live_video --coverage-text"

Troubleshooting: Caching Issues

Standard Drupal blocks often suffer from the Internal Page Cache limitation, where the max-age of a block is ignored and the entire page is cached permanently for anonymous users.

Drupal core's Internal Page Cache module ignores max-age bubbled metadata. To ensure the Cache-Control header correctly reflects the configured "Cache Duration" even when the Internal Page Cache is active, it is recommended to install the page_cache_max_age_bubbling module.

YouTube Live Video uses AJAX to retrieve the block content because it seems that blocks in regions outside of the main content have a different bubbling strategy and won't bubble to the top even when using the above module. By retrieving with AJAX, the request is handled in isolation and gets the proper max-age and expires time.

Advanced Caching

If you are using external caches (Varnish, Cloudflare, etc.), ensure they are configured to respect the Cache-Control: max-age header returned by the AJAX endpoint (/youtube-live-video/render).