View source for Module:Screencap/doc

== Overview ==
'''Module:Screencap''' is the Lua backend for [[Template:Screencap]], the unified image tag for BattlestarWiki Media. It replaces the fragmented family of legacy sub-templates ({{Master screencap}}, {{TOS BR screencap}}, {{Caprica HDTV broadcast screencap}}, etc.) with a single module that auto-detects as much metadata as possible from the file itself, while allowing any detected value to be overridden via named template parameters.

The module does four things:
# Detects the '''series''' from filename prefix patterns
# Detects the '''season and episode''' from filename patterns (SxxExx, NxNN, or prose title hint)
# Detects the '''source type / quality tier''' from the file's pixel dimensions
# Renders a collapsible '''infobox''' and applies '''maintenance categories'''

== Entry Point ==
The module exposes one public function:

{| class="wikitable"
! Function !! Called by !! Description
|-
| <code>p.main(frame)</code> || <code><nowiki>{{#invoke:Screencap|main}}</nowiki></code> in [[Template:Screencap]] || Full pipeline: detect → render infobox → emit categories
|}

== Series Detection ==
Series is detected by matching the start of the filename against a prefix table. Matching is case-sensitive on the prefix but tolerates spaces or underscores as separators (e.g. <code>RDM -</code>, <code>RDM_</code>).

{| class="wikitable"
! Filename starts with !! Detected <code>series</code> key
|-
| <code>RDM -</code>, <code>TRS -</code>, <code>BSG - S##</code>, <code>BSG - #x##</code> || <code>rdm</code>
|-
| <code>CAP -</code>, <code>Caprica -</code> || <code>cap</code>
|-
| <code>B&C -</code>, <code>BNC -</code> || <code>bnc</code>
|-
| <code>TOS -</code> || <code>tos</code>
|-
| <code>1980 -</code>, <code>G1980 -</code> || <code>1980</code>
|-
| ''(no match)'' || <code>unknown</code>
|}

Each series key maps to a <code>SERIES_META</code> entry containing the human-readable name, category abbreviation, wiki article links, and copyright holder used in the infobox.

To add a new series, add a new entry to both <code>SERIES_PREFIXES</code> and <code>SERIES_META</code> in the module.

== Episode & Season Detection ==
The module attempts to extract season and episode numbers from the filename in this priority order:

{| class="wikitable"
! Pattern !! Example filename !! Result
|-
| <code>SxxExx</code> (standard) || <code>RDM - S04E20 - Daybreak.jpg</code> || Season 4, Episode 20
|-
| <code>NxNN</code> (alternate) || <code>BSG - 1x05 - Act of Contrition.jpg</code> || Season 1, Episode 5
|-
| Prose title hint || <code>TOS - The Lost Warrior - Apollo.jpg</code> || Title hint: "The Lost Warrior - Apollo"
|-
| ''(no match)'' || <code>Adamabed.jpg</code> || No season, no episode, no hint
|}

When only a title hint is extracted (no season/episode numbers), the infobox displays the hint with a message asking editors to verify and supply the full episode name. When nothing is extracted at all, the infobox flags the image as unidentified and links to the talk page.

Note: the <code>|episode=</code> parameter is '''not''' auto-detected from the filename — it must be explicitly supplied if you want a linked episode name in the infobox. The filename extraction only produces season/episode numbers or a hint string.

== Source Type Detection ==
When no <code>|type=</code> override is supplied, the module reads the file's pixel dimensions via <code>mw.title.getCurrentTitle().file</code> and classifies the source using the longest pixel axis (so portrait-orientation promotional photographs are handled correctly alongside landscape screencaps).

{| class="wikitable"
! Longest pixel dimension !! Detected <code>type</code> !! Label shown
|-
| ≥ 3840 px || <code>4k</code> || 4K Ultra HD screen capture
|-
| ≥ 1920 px || <code>bluray</code> || Blu-ray screen capture
|-
| ≥ 1280 px || <code>hdtv</code> || HD broadcast screen capture
|-
| ≥ 853 px || <code>ntscdvd</code> || NTSC DVD screen capture
|-
| ≥ 720 px || <code>paldvd</code> || PAL DVD screen capture
|-
| < 720 px || <code>dvd</code> || DVD screen capture
|-
| ''dimensions unavailable'' || <code>unknown</code> || screen capture (source unknown)
|}

Dimensions are unavailable when the module runs outside a File: page context (e.g. during template sandbox testing), in which case it falls back gracefully to <code>unknown</code> rather than erroring.

All valid <code>type</code> keys that can be used as overrides:

{| class="wikitable"
! Key !! Description
|-
| <code>4k</code> || 4K UHD Blu-ray (≥ 3840px)
|-
| <code>bluray</code> || Blu-ray / 1080p stream
|-
| <code>hdtv</code> || HD broadcast or download
|-
| <code>hddvd</code> || HD DVD (manual override only — not auto-detected)
|-
| <code>itunes</code> || iTunes / digital download (manual override only)
|-
| <code>ntscdvd</code> || NTSC DVD
|-
| <code>ntscb</code> || NTSC broadcast (manual override only)
|-
| <code>paldvd</code> || PAL DVD
|-
| <code>palb</code> || PAL broadcast (manual override only)
|-
| <code>promo</code> || Promotional photograph (manual override only)
|-
| <code>dvd</code> || Generic / low-res DVD
|-
| <code>unknown</code> || Source unknown
|}

<code>hddvd</code>, <code>itunes</code>, <code>ntscb</code>, <code>palb</code>, and <code>promo</code> cannot be auto-detected from dimensions alone and must always be set via <code>|type=</code>.

== Timestamp Handling ==
The <code>|timestamp=</code> parameter accepts three input formats:

{| class="wikitable"
! Input !! Interpretation !! Displayed as
|-
| <code>427</code> || Bare integer → total seconds || <code>00:07:07</code>
|-
| <code>3662</code> || Bare integer → total seconds || <code>01:01:02</code>
|-
| <code>00:07:07</code> || Already HH:MM:SS || <code>00:07:07</code>
|-
| <code>0h20m42s</code> || Non-numeric string → passed through || <code>0h20m42s</code>
|}

Any input that does not parse as a pure number via <code>tonumber()</code> is passed through as-is, so existing timestamps in any format continue to work without changes.

== Infobox Output ==
The rendered infobox is a standard MediaWiki wikitable with class <code>wikitable mw-collapsible screencap-infobox</code>. Rows are emitted in this order:

# Header — source type icon + label (collapsible toggle)
# Series / episode identification line with language bar links
# Copyright notice (links to Wikipedia)
# Timestamp (or missing-timestamp notice)
# Source description and native resolution
# Detected pixel dimensions (if available)
# Scaling note (if <code>|scaled=yes</code>)
# Cropping note (if <code>|cropped=yes</code>)
# Aspect ratio confirmation (if <code>|aspect=yes</code>)

=== Cross-wiki icon rendering ===
Source type icons are referenced using standard <code><nowiki>[[File:Name|30px|link=]]</nowiki></code> wikitext. The language wikis (de., fr., etc.) serve these files via ForeignAPIRepo from media.battlestarwiki.org, so the icons render correctly everywhere without any special URL construction.

== Category Output ==
Categories are appended after the infobox and applied automatically — no manual <code><nowiki>[[Category:...]]</nowiki></code> tags are needed on file pages.

For a Blu-ray RDM image of "Daybreak" from Season 4, the following categories would be applied:

* <code><nowiki>[[Category:Screen captures]]</nowiki></code>
* <code><nowiki>[[Category:Screen captures (TRS)]]</nowiki></code>
* <code><nowiki>[[Category:Blu-ray screen captures (TRS)]]</nowiki></code>
* <code><nowiki>[[Category:Screen captures by season 4 (TRS)]]</nowiki></code>
* <code><nowiki>[[Category:Screen captures (Daybreak)]]</nowiki></code>
* <code><nowiki>[[Category:Blu-ray screen captures (Daybreak)]]</nowiki></code>

Additional maintenance categories are applied automatically based on conditions:

{| class="wikitable"
! Condition !! Maintenance category added
|-
| <code>type</code> is <code>unknown</code> || <code>Screen captures requiring source identification</code>
|-
| <code>type</code> is <code>ntscdvd</code>, <code>paldvd</code>, <code>ntscb</code>, or <code>palb</code> || <code>Screen captures requiring upgrade</code>
|}

== Extending the Module ==
=== Adding a new series ===
Add one or more entries to <code>SERIES_PREFIXES</code> (for filename detection) and a corresponding entry to <code>SERIES_META</code> (for display metadata):

<syntaxhighlight lang="lua">
-- In SERIES_PREFIXES:
{ pattern = "^BLOOD%s*[-_]%s*", series = "bnc" },

-- In SERIES_META:
bnc = {
    name      = "''Battlestar Galactica: Blood & Chrome''",
    abbr      = "BNC",
    enlink    = "Battlestar Galactica: Blood & Chrome",
    copyright = "Universal Studios / Syfy",
},
</syntaxhighlight>

=== Adding a new source type ===
Add an entry to <code>TYPE_LABELS</code> and a corresponding entry to the <code>iconMap</code> inside <code>renderInfobox</code>:

<syntaxhighlight lang="lua">
-- In TYPE_LABELS:
webdl = { short = "Web DL", long = "web download screen capture", badge = "Web DL", res = "variable" },

-- In iconMap inside renderInfobox:
webdl = "[[File:BSG WIKI WebDL.png|30px|link=]]",
</syntaxhighlight>

== See Also ==
* [[Template:Screencap]] — the template that invokes this module
* [[Template:Screencap/doc]] — end-user documentation and parameter reference
* [[Template:Master screencap]] — legacy parent template (now a wrapper)
* [[Battlestar Wiki Media:Image tagging policy]]

<includeonly>[[Category:Lua modules]]</includeonly>
<noinclude>[[Category:Module documentation]]</noinclude>