Videos Module

The /videos page is the public-facing Matters AI video gallery. It pulls every video from the WordPress video CPT, renders a hero + featured slot + filterable grid + deep-link modal player, and emits VideoObject + ItemList JSON-LD for SEO.

This module follows the CPT-backed module pattern — read that page first for the shared blueprint. This page documents the video-specific details.

The ProductVideo shape#

Every video the gallery renders conforms to this shape — both the static fallback registry and the live CPT data are mapped to it before consumption:

// lib/data/product-videos.ts
export type ProductVideoCategory =
  | "platform"
  | "integrations"
  | "use-cases"
  | "events"
  | "company";

export interface ProductVideo {
  slug: string;                  // Deep-link key: /videos?v=<slug>
  title: string;
  description: string;           // Card description (1–2 sentences)
  longDescription?: string;      // Featured-slot description
  playbackId: string;            // Mux playback ID — required
  assetId: string;               // Mux asset ID — used for analytics
  youtubeId?: string;            // Optional — shows "Watch on YouTube" link in modal
  duration?: string;             // e.g. "2:14"
  category: ProductVideoCategory;
  tags: string[];
  featured?: boolean;            // Hero slot (only one wins)
  relatedLinks?: { title; href; kind?: "Blog" | "Datasheet" | "Webinar" | "Docs" | "Page" }[];
}

The CPT's content.raw stores this JSON minus slug and title (those map to WP's native post.slug and post.title).

Data flow#

Workspace edit form  ──┐
                       │  PUT /api/workspace/videos/<id>
                       ▼
              WP video CPT (private)
                       │
                       │  GET /wp-json/wp/v2/video?status=publish
                       ▼
       lib/data/videos-server.ts → getProductVideos()
                       │
       (if CPT empty / errors → falls back to PRODUCT_VIDEOS static array)
                       ▼
        app/videos/page.tsx (server)
                       │  passes videos + featured as props
                       ▼
     app/videos/client-page.tsx (client)
                       │
   ┌───────────────────┼───────────────────┐
   ▼                   ▼                   ▼
 FeaturedVideo     CategoryFilter       VideoCard grid
                                        + ?v=<slug> deep-link
                                        → VideoModal

Key files#

WordPress side#

The video CPT is registered in WP admin via the Simple CPT plugin. Settings:

Workspace admin#

Public website#

Static fallback strategy#

getProductVideos() returns one of three sources:

The source is typed "wordpress" | "fallback" | "empty" (videos-server.ts:54), but in practice getProductVideos() only ever returns two of them:

Every failure path resolves to "fallback", so /videos never shows an empty gallery during migration or downtime. Once you publish CPT entries, those override the static fallback automatically.

Deep-link modal pattern#

The gallery is a single page (/videos); individual videos open in a modal via a query param:

/videos              → gallery only
/videos?v=funding-journey  → opens that video's modal on load

Implemented in client-page.tsx:

useEffect(() => {
  const slug = searchParams.get(QUERY_KEY);
  if (!slug) {
    setActiveVideo(null);
    return;
  }
  const match = videos.find((v) => v.slug === slug);
  if (match) setActiveVideo(match);
}, [searchParams, videos]);

Sharing a ?v=... URL gets the recipient straight into the right modal — used by the navbar "Resources" carousel and as the workspace's "View Live" action.

SEO#

The server page injects:

1. ItemList — the full gallery, lets Google show "video carousel" rich results.
2. VideoObject per video — name, description, Mux thumbnail, m3u8 content URL, embed URL pointing to /videos?v=<slug>.

If you change the uploadDate field (currently hardcoded "2025-01-01"), make it dynamic from the WP post's modified field.

The Google sitemap entry lives at app/(sitemaps)/sitemap-videos.xml/route.ts — note that one scans blog posts for embedded YouTube/Mux/Vimeo videos, not the video CPT. The CPT sitemap entry doesn't exist yet — add it if you want individual gallery deep-links indexed.

Navbar consumption#

The Resources carousel in components/nav/Navbar.tsx already fetches live data. It seeds navVideos from the static PRODUCT_VIDEOS array (via SOCIAL_VIDEOS_MATTERS) so the carousel paints immediately, then a useEffect (~line 247) fetches /api/videos/list with { cache: "no-store" } and swaps in the live CPT data once it resolves. Any failure (non-ok response, empty list, or thrown error) silently keeps the static seed, so the carousel always works. React Query is not used — it's a plain fetch inside a useEffect with a cancelled guard.

Adding a new video#

1. Open workspace.matters.ai/videos → New Video.
2. Fill the form (Mux playback ID is required).
3. Set status to Published and save.
4. The public site picks it up within ~1 hour — the getProductVideos() fetch is tagged ["videos"] with revalidate: 60 * 60. (Note: the workspace videos API routes do not currently call revalidateTag("videos"), so a published change surfaces when the 1-hour TTL elapses rather than instantly.)

Gotchas#

• playbackId is required. Server-side mapper drops any CPT entry without one (see videos-server.ts:97-98).
• Only one featured should be true. The picker uses the first match; backstop warning in the workspace UI is a TODO.
• The static fallback is intentional. Don't remove product-videos.ts until every video is migrated to the CPT and verified. It's our safety net.

Related#

• CPT-Backed Module Pattern — the shared blueprint
• Snippet Generators — the videoplayer snippet block is how Mux videos get embedded inside blog posts (different surface from this gallery)
• SEO & Analytics — VideoObject JSON-LD spec