How mattwright324/youtube-metadata works
1. Overall shape
- This is a static, client-side web app for inspecting YouTube metadata, not a server-backed system.
- The repository is organized like a Jekyll site: index.html, bulk.html, and search.html are the main entry pages, with _layouts and _includes providing shared page structure and form controls.
2. Primary user-facing surfaces
- There are three main workflows:
- Single metadata lookup on the main page
- Bulk metadata retrieval in bulk.html
- Search-based discovery in search.html
- The README’s emphasis on shareable links and viewing “all metadata” suggests the app is designed around URL-driven state and reusable views.
3. Core data source boundary
- The main external dependency is the YouTube Data API v3.
- js/youtube-api-v3.js is the likely API access layer that handles request construction and result retrieval.
- The app’s primary architectural boundary is therefore browser UI → YouTube API → normalized metadata display.
4. Shared client-side application layer
- js/shared.js appears to hold common utilities used across all pages: shared state handling, formatting helpers, DOM wiring, and generic UI logic.
- js/translators.js is a distinct enrichment layer for converting or interpreting values such as language/country codes and other API fields into human-readable forms.
5. Single-item metadata workflow
- js/youtube-metadata.js is the core page controller for the main metadata experience.
- From the README, this path takes a video, playlist, or channel identifier, fetches every available API part, and renders both raw and interpreted metadata.
- This is the central “inspect one resource deeply” flow.
6. Bulk retrieval workflow
- js/youtube-metadata-bulk.js supports batch input and multi-item extraction.
- This subsystem exists for playlist/channel fan-out use cases, where the app enumerates many videos and gathers metadata at scale.
- It likely shares the same API and formatting helpers, but with batch-specific progress and result aggregation logic.
7. Search/discovery workflow
- js/youtube-metadata-search.js implements search-oriented discovery, likely querying YouTube search results and then drilling into returned items.
- This page is a separate entry point because search has different input/output behavior than direct metadata lookup.
- Architecturally, it sits beside the other flows rather than inside them, but still depends on the same shared API and UI utilities.
8. Enrichment and investigative features
- The README highlights OSINT-oriented features: interpreting missing vs found fields, translations, geolocation links, reverse image search, and external lookup shortcuts.
- Those are not separate services in this repo; they are client-side enrichments layered on top of API results and surfaced in the UI.
- This means the app’s “processing” stage is mostly about presentation and interpretation, not backend computation.
9. Import/export boundary
- The app supports exporting and importing data as zip archives, plus raw JSON and CSV.
- css/export.user.css and the README’s export/import notes indicate a dedicated output path for archived/shareable datasets.
- This creates a second major data flow: API response → packaged export → later re-import into the same UI.
10. Presentation system
- css/youtube-metadata.css is the main application stylesheet; css/export.user.css is likely specialized for exported output or browser-user-style usage.
- _layouts/default.html and _includes/form_controls.html / _includes/formats.html suggest the UI is built from reusable form and formatting partials.
- The img/ assets are part of the user-facing documentation and app branding, not core logic.
11. Build and hosting model
- Gemfile, _config.yml, and the Jekyll directory structure show the site is built with the Ruby/Jekyll toolchain.
- That means the repo likely produces a static site that can be hosted without a backend, with Jekyll assembling common page chrome and assets during build time.
12. Important architectural takeaway
- The system is best understood as a static, multi-page investigative frontend:
- Pages provide workflows
- Shared JS provides common behavior
- One module talks to YouTube
- Separate modules handle single-item, bulk, and search flows
- Enrichment/formatting stays in-browser
- Export/import preserves data for offline or later review
Main entry points: index.html Main page · default.html Default layout · youtube-metadata.js Metadata flow · bulk.html Bulk page
Components 17
Build & shell
Jekyll/static site scaffolding and shared page chrome.
- Default layout · Shared page chrome and structure for the site.
_layouts/default.html - Form controls · Reusable input controls and form wiring.
_includes/form_controls.html - Formats partial · Reusable format and display templates.
_includes/formats.html - Site config · Jekyll build configuration and site metadata.
_config.yml
User pages
Main entry pages and workflow surfaces.
- Main page · Single-item metadata lookup and inspection surface.
index.html - Bulk page · Batch metadata retrieval workflow.
bulk.html - Search page · Search-driven discovery workflow.
search.html
Client logic
Browser-side application modules for API access, shared behavior, and workflow controllers.
- Shared logic · Common utilities, state handling, and DOM helpers shared across pages.
js/shared.js - Translators · Human-friendly interpretation of codes and metadata values.
js/translators.js - YouTube API · YouTube Data API v3 request construction and retrieval.
js/youtube-api-v3.js - Metadata flow · Core single-resource lookup and metadata rendering workflow.
js/youtube-metadata.js - Bulk flow · Multi-item extraction, fan-out, and aggregation workflow.
js/youtube-metadata-bulk.js - Search flow · Search-based discovery and drill-in workflow.
js/youtube-metadata-search.js - Examples · Example inputs and usage patterns for the app.
js/youtube-metadata-examples.js
Assets
Styles and media used by the site and exports.
- App styles · Primary visual styling for the metadata interface.
css/youtube-metadata.css - Export styles · Specialized styling for exported or user-style output.
css/export.user.css - Brand assets · Icon and visual assets used by the site and documentation.
img/icon.pdn
Connections 24
- Default layout → Main page: wraps · Shared layout frames the main page.
- Default layout → Bulk page: wraps · Shared layout frames the bulk page.
- Default layout → Search page: wraps · Shared layout frames the search page.
- Form controls → Main page: injects UI · Reusable controls support the main lookup form.
- Form controls → Bulk page: injects UI · Reusable controls support batch input.
- Form controls → Search page: injects UI · Reusable controls support search inputs.
- Formats partial → Main page: injects UI · Shared formatting templates support metadata rendering.
- Shared logic → Metadata flow: supports · Shared helpers are used by the single-item controller.
- Shared logic → Bulk flow: supports · Shared helpers are used by the bulk controller.
- Shared logic → Search flow: supports · Shared helpers are used by the search controller.
- Translators → Metadata flow: enriches · Code and value translation enhances metadata display.
- YouTube API → Metadata flow: fetches · Single-item flow drives YouTube API requests.
- YouTube API → Bulk flow: fetches · Bulk flow reuses the same API client for fan-out retrieval.
- YouTube API → Search flow: fetches · Search flow queries YouTube through the API client.
- Metadata flow → Main page: powers · Main page controller powers single-resource lookup.
- Bulk flow → Bulk page: powers · Bulk controller powers the batch workflow.
- Search flow → Search page: powers · Search controller powers the discovery workflow.
- Examples → Main page: demonstrates · Example inputs help illustrate supported usage.
- App styles → Main page: styles · Primary stylesheet applies to the main experience.
- App styles → Bulk page: styles · Primary stylesheet applies to the bulk experience.
- App styles → Search page: styles · Primary stylesheet applies to the search experience.
- Export styles → Main page: styles · Export-oriented styling supports packaged output and review.
- Site config → Default layout: configures · Jekyll settings drive site assembly.
- Brand assets → Default layout: brands · Visual assets support the site shell and documentation.