sgalinski/sg-video

Unified TYPO3 video/mediathek element for YouTube, Vimeo, and local FAL files; output videos, playlists, channels, and groups/showcases, and migrate from sg_youtube and sg_vimeo.

Maintainers

Package info

gitlab.sgalinski.de/typo3/sg_video.git

Homepage

Type:typo3-cms-extension

pkg:composer/sgalinski/sg-video

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Security

Advisories: 0

Aikido package health analysis

1.0.7 2026-04-18 16:15 UTC

Requires

Replaces

  • sgalinski/sg_video: 1.0.7

GPL-2.0-or-later 69f8876cfdf29bb633a9aa8a5d954ef3ac0a51bd

This package is auto-updated.

Last update: 2026-04-18 16:19:45 UTC

README

sgalinski logo

License: GNU GPL, Version 2

Repository: https://gitlab.sgalinski.de/typo3/sg_video

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_video/-/issues

Overview

sg_video is the unified successor for sg_youtube and sg_vimeo.

It provides one TYPO3 content element (tt_content.CType = sgvideo_video) with a provider switch:

  • YouTube
  • Vimeo
  • Custom (local TYPO3/FAL video files)

For migrated YouTube/Vimeo records, frontend behavior and look/feel are aligned with the legacy extensions. The main namespace change for integrators is:

  • sg-youtube / sg-vimeo -> sg-video

Requirements

  • TYPO3: ^13.4 || ^14.0
  • PHP: 8.3+

Installation

Composer

composer require sgalinski/sg-video

TYPO3 integration

  1. Activate sg_video in TYPO3 Extension Manager.
  2. Include static TypoScript: SG Video (EXT:sg_video/Configuration/TypoScript).

Configuration

Credentials are configured via TypoScript constants:

plugin.tx_sgvideo.settings.providers.youtube.apiKey = <key>
plugin.tx_sgvideo.settings.providers.vimeo.clientId = <id>
plugin.tx_sgvideo.settings.providers.vimeo.clientSecret = <secret>
plugin.tx_sgvideo.settings.providers.vimeo.personalAccessToken = <token>

Environment fallback keys (read directly by providers):

  • SG_VIDEO_YOUTUBE_API_KEY
  • SG_VIDEO_VIMEO_PERSONAL_ACCESS_TOKEN
  • SG_VIDEO_VIMEO_CLIENT_ID
  • SG_VIDEO_VIMEO_CLIENT_SECRET

website_base/project_theme style env wiring

If you already use existing website_base variables, map them in your project TypoScript:

plugin.tx_sgvideo.settings.providers.youtube.apiKey := getEnv(SITE_WEBSITE_BASE_SGYOUTUBEAPIKEY)
plugin.tx_sgvideo.settings.providers.vimeo.clientId := getEnv(SITE_WEBSITE_BASE_SGVIMEOCLIENTID)
plugin.tx_sgvideo.settings.providers.vimeo.clientSecret := getEnv(SITE_WEBSITE_BASE_SGVIMEOCLIENTSECRET)

Usage

Add content element sgvideo_video and configure:

  • provider: youtube|vimeo|custom
  • source kind:
    • YouTube: video|channel|playlist
    • Vimeo: video|channel|showcase
    • Custom: file
  • source identifier / file reference

Available frontend layouts:

  • default
  • rows
  • playlist

Implemented behavior includes:

  • unified filters (searchTerm, duration)
  • read-more / read-less behavior
  • lightbox and no-lightbox behavior parity
  • structured data JSON-LD output via StructuredVideoDataViewHelper

For custom/local videos:

  • files are resolved from settings.fileReference relation first
  • sys_file_reference.autoplay is respected in lightbox and inline no-lightbox rendering

Caching and cache bypass

Provider responses use cache sgvideo_cache (24h TTL for provider responses).

Supported URL parameters for bypassing provider cache:

  • canonical: disableSgVideoCache=1
  • legacy aliases:
    • disableYoutubeCache=1
    • disableVimeoCache=1

HTTP request behavior

Provider HTTP calls use explicit timeout settings:

  • connect timeout: 2s
  • request timeout: 8s

Retry/backoff is intentionally not enabled in this release.

Events

sg_video exposes the unified event lifecycle:

  • SGalinski\SgVideo\Event\BeforeProviderCallEvent
  • SGalinski\SgVideo\Event\AfterProviderCallEvent
  • SGalinski\SgVideo\Event\AfterFilterVideosEvent
  • SGalinski\SgVideo\Event\AfterMapCustomThumbnailsEvent

Migration from sg_youtube / sg_vimeo

Migration is handled by TYPO3 upgrade wizard:

  • wizard id: sgvideo_contentElementMigration
  • migrates legacy CType and legacy list_type records to sgvideo_video
  • maps legacy FlexForm schema to sg_video
  • migrates legacy thumbnail relation field names to settings.thumbnailImages

Template override note:

  • sg_video uses one unified template entrypoint (Video/Index.html).
  • Provider-specific template overrides are no longer split by tx_sgyoutube / tx_sgvimeo.
  • Existing custom Vimeo/YouTube templates must be migrated manually to the sg_video template contract.

Rector/Fractor migration tooling is intentionally de-scoped for this release. The TYPO3 upgrade wizard is the canonical migration path.

See detailed integrator steps in UPGRADE.md.

Non-composer installations

No Vimeo SDK package or PHAR fallback is required.

sg_video uses direct HTTP requests (RequestFactory) for Vimeo API access, so the following are not required:

  • vimeo/vimeo-api
  • Libraries/vimeo-api.phar

Frontend assets (sgc)

Build assets from extension root:

npm install

Note:

  • The lightbox dependency is vendored in Resources/Public/JavaScript/Modules/Vendor/BasicLightbox/.
  • sgc build does not require extension-local node_modules/basiclightbox.

If you work inside a website_base monorepo with sgc:

./sgc-core/core/sgc build --ext sg-video

For watcher-based frontend development in website_base, also update .sgc-config.js:

  • add sg-video to extensions
  • add sg-video to watchExtensions
  • add these JS libraryPaths entries:
    • ./vendor/sgalinski/sg-video/Resources/Public/JavaScript/Modules
    • ./vendor/sgalinski/sg-video/Resources/Public/JavaScript

Generated minified assets in Resources/Public/JavaScript/Dist/ and Resources/Public/StyleSheets/ are shipped and versioned.

Testing

Run from website_base project root (monorepo usage):

composer ecs vendor/sgalinski/sg-video
composer phpstan local/sg_video
vendor/bin/phpunit --configuration local/sg_video/phpunit.xml.dist