View source for Help:VOD script

When a new Critical Role episode is released on YouTube, there are a number of wiki updates that need to performed. Most of these are done semi-automatically by running a pywikibot script.

== Tasks performed, in order ==
Checklist for when new VOD is uploaded to YouTube
{| class="wikitable"
|-
! Script command !! Editing task
|-
| <code>-update_page</code> || Add thumbnail, VOD URL, and runtime to article infobox.
|-
| <code>-move</code> || Move article from its placeholder generic title to the actual title.
|-
| <code>-upload</code> || Upload YouTube VOD thumbnail.
|- 
| <code>-ep_array</code>|| Update episode name in [[Module:Ep/Array]] and make sure the relevant "latest" code (e.g., <code>c3 latest</code>) is in altCodes
|-
| <code>-yt_switcher</code> || Add VOD URL to [[Module:Ep/YTURLSwitcher/URLs]].
|- 
| <code>-ep_list</code> || Add VOD URL and runtime to applicable list article, such as [[List of Campaign 3 episodes]] or [[One-shots]].
|-
| <code>-redirects</code> || Create/update redirects from valid episode codes to the new episode name
|-
| <code>-navbox</code> || Add episode to appropriate navigation template, such as {{tl|Nav-C3Arc1}}, {{tl|Nav-OneShots}}, or {{tl|Nav-Bitsnbobs‎}}.
|-
| <code>-cite_cat</code> || Create maintenance category for the episode, such as [[:Category:Articles needing citations/4SDx21]].
|-
| <code>-airdate_order</code> || Add airdate to [[Module:AirdateOrder/Array]].
|-
| <code>-4SD</code> || For new ''[[4-Sided Dive]]'' episodes only. For the [[Campaign 3]] episodes that aired since the previous 4SD, add the current 4SD episode code to the <code>4SD</code> infobox parameter.
|-
| <code>-transcript</code> || Generate a transcript on a Transcript: episode page (automatically skips shows like ''[[4-Sided Dive]]''). 
|-
| <code>-ignore_break</code> || Manually override break checking for campaign episodes. 
|-
| <code>-transcript_list</code> || Add link to transcript page on [[Transcripts]].
|-
| <code>-long_short</code> || Checks whether the episode belongs on [[Longest and shortest episodes]].
|-
| <code>-appendix</code> || Interactive prompt for creating [[Module:Midst appendices/Array]] entry.
|-
| <code>-all</code> || Performs every tasks above that hasn't been completed yet.
|-
! colspan=3 | Download/update data
|-
| <code>-decoder</code> || Forces a local re-download of [[Module:Ep/Decoder]] (placed in a /data/ subfolder).
|-
| <code>-actor_data</code> || Forces a local re-download of [[Module:ActorData]] (placed in a /data/ subfolder).
|-
| <code>-download_data</code> || Forces a local re-download of both [[Module:Ep/Decoder]] and [[Module:ActorData]].
|}

You can run any subset of these tasks as well. For every potential change, you will be shown a diff of the edit and asked to accept or reject it. No changes will be made automatically. Actions are skipped if change is not needed (e.g., an entry for the episode already exists on the module page). Use global <code>-simulate</code> option for testing, where no changes to the live wiki will be done, but it will do everything else other than save the changes (e.g., download the thumbnail).

== Episode data to pass to script ==
Only two of these fields are required. If you run a task above that requires one of these fields below that isn't entered, you will be prompted to enter that value.

{| class="wikitable"
|-
! Script command !! Data type !! Required?
|-
| <code>-ep:</code> || The CxNN code of the episode || Required
|- 
| <code>-page:</code> || The pagename to be edited, usually current episode page || Required
|- 
| <code>-yt:</code> || The 11-character unique identifier or full URL for the YouTube video. Can include multiple (yt1, yt2, vod, vod2, etc) || Optional
|- 
| <code>-airdate:</code> || YYYY-MM-DD of the date episode aired. Can be inferred from episode page if filled in. Also accepts MM-DD-YYYY.|| Optional
|- 
| <code>-airtime:</code> || Time of day the episode aired. Can be inferred from episode page if filled in. || Optional
|- 
| <code>-runtime:</code> || HH:MM:SS vod length. If multiple vods, place each runtime in same order; values automatically summed || Optional
|- 
| <code>-actors:</code> || L-R of actors in thumbnail. Separate with ','. First names ok (from ACTORS list) || Optional
|-
| <code>-episode_summary:</code> || The 1-2 line summary of the episode from the YouTube video. || Optional
|- 
| <code>-old_ep_name:</code> || If different from <code>-page:</code>, the current name of the episode (mostly for testing) || Optional
|- 
| <code>-new_ep_name:</code> || The new title of the episode, if changed || Optional
|- 
| <code>-new_page_name:</code> || Only needed if page name differs from <code>new_ep_name</code> (usually 'A' vs 'A (episode)') 
|- 
| <code>-image_name:</code> || Only needed if not using default thumbnail name || Optional
|- 
| <code>-host:</code> || Actor who is the 4SD host or running one-shot (DM, GM also work here) || Optional
|- 
| <code>-game_system:</code> || For one-shots, game system if ''not'' Dungeons & Dragons || Optional
|- 
| <code>-file_desc:</code> || When uploading image, the file description to use instead of the generated one || Optional
|- 
| <code>-caption:</code> || When uploading image, the infobox caption to use instead of the generated one || Optional
|- 
| <code>-airsub:</code> || The earlier date the episode released to subscribers || ''Midst'' only
|- 
| <code>-transcript_link:</code> || The url of the transcript || ''Midst'' only
|- 
| <code>-icon_url:</code> ||  The url of the .png episode icon || ''Midst'' only
|- 
| <code>-illustrator:</code> || The illustrator of the thumbnail/icon art || ''Midst'' only
|- 
| <code>-logline:</code> || Used as quote in the first quotebox || ''Midst'' only
|}

== Module data to be maintained ==
{{See also|Help:Maintaining data modules}}
Some modules contain data that the script uses that may need to be updated from time to time. These should be edited on-wiki if their information changes. The next time running the script add the appropriate flags (e.g., <code>-decoder</code>) to make sure the updated data is downloaded locally and replaces any existing file. Any editor can make these changes and you don't need to know Python or Lua.

{| class="wikitable"
|-
! Module !! Usage !! When to update
|-
| [[Module:ActorData]] || The full list of potential cast members of a new episode, plus their speaker tags || New guest stars or cast members appear.
|-
| [[Module:Ep/Decoder]] || <code>'noTranscript'</code> parameter for shows to skip for transcript creation (currently <code>4SD, LVM2</code>) || A new campaign airs that should not have transcripts downloaded.
|}

== Setting up pywikibot ==
=== Generate a bot password ===
You can create a special password just for pywikibot at [[Special:BotPasswords]]. You should use a unique bot password for every method you use to programmatically access the wiki. You may also want to create a special wiki account for automated editing with a [https://criticalrole.miraheze.org/w/index.php?title=Special:ListUsers&group=bot bot flag].

=== Install Python 3 and pywikibot ===
You will need at least Python 3.9 to run this script. To see if you have python 3 installed, open your [[W:Command-line interface|command line interface]] (CLI) and type <code>python --version</code>. If it's not 3.9 you can download it [https://www.python.org/downloads/ here] and install it. Once you've verified that <code>python --version</code> is at least 3.9, run <code>pip install pywikibot nltk youtube_transcript_api</code>. If you have a Windows machine, you will also need to run <code>pip install tzdata</code>.

=== Set up pywikibot ===
Follow the installation instructions [https://github.com/eseiver/cr_miraheze_scripts/blob/main/Readme.md here] to clone the script repository. Make sure the pywikibot folder/directory is somewhere easily accessible. In your CLI, navigate to the pywikibot directory. Generate the wiki-specific files you need for logging in by following the [https://www.mediawiki.org/wiki/Manual:Pywikibot/Use_on_third-party_wikis configuration guide for third-party wikis]; <code>miraheze_family.py</code> does not exist by default and must be created. Your login credentials will be stored in <code>user-config.py</code> and <code>user-password.py</code>.

Update your <code>user-config.py</code> file in pywikibot to include:
<code>user_script_paths = ['scripts.userscripts.cr_miraheze_scripts']</code>

=== Updating the script ===
To get the latest pywikibot updates, go into the pywikibot folder and run <code>git pull</code>. To update the miraheze scripts, run <code>git -C scripts/userscripts/cr_miraheze_scripts pull</code>. Git updates will not overwrite any user files.

=== Updating local data ===
This code base depends on the data stored in [[Module:Ep/Decoder]] and [[Module:ActorData]]. The module data is downloaded automatically the first time it is accessed, but will not update unless manually prompted by the user. There are two ways you can update it:
* While running the VOD script, pass in the parameter <code>-download_data</code>
* Separately run <code>python pwb.py download_data</code>

== Running the script ==
To run the script on the command line, make sure you are in the pywikibot top-level folder. Here's what it looked like for episode 3x26:

<code>python pwb.py vod -all -ep:3x26 -page:"Campaign 3, Episode 26" -yt:"UOWp-b9aoWQ" -new_ep_name:"Hidden Truths" -runtime:4:10:24 -episode_summary:"Bells Hells seek out allies and options in their evolving plan to infiltrate Paragon’s Call…" -actors:"Marisha, Sam, Laura"</code>

More documentation about <code>vod.py</code> can be found on [https://github.com/eseiver/cr_miraheze_scripts/blob/main/vod.py its page].

'''Notes:'''
{{Reflist|group="fn"}}
[[Category:Help]]