Introduce Powershell Script and Config Generator

scripts/powershell/eclipse/README.md

@@ -0,0 +1,124 @@
+# Powershell Companion Script
+#### Author: [Scott Sousa](https://scottjsousa.com/)
+
+This script serves as a companion script to SharpCap Eclipse Sequencer scripts. This script plays audible announcements at scheduled times throughout the eclipse. You will need a device with a speaker or audio output.
+
+My current setup uses a mini-PC attached to my rig. Using [Windows Remote Desktop](https://support.microsoft.com/en-us/windows/how-to-use-remote-desktop-5fe128d5-8fb1-7a23-3b8a-41e636865e8c) on a [tablet](https://apps.apple.com/us/app/microsoft-remote-desktop/id1295203466), my mini-PC is able to broadcast audio through the tablet. This is my "speaker".
+
+*Note: This script has only been tested on Windows 11 and may not work with other operating systems.*
+
+## Installation and Usage
+
+1. Open SharpCap Eclipse Sequencer
+2. Download Powershell script and assets zip archive (*Note: The download button is at the top of the page and also in the "Generated Powershell Script Config" section*)
+3. Extract the zip archive to `{SHARPCAP_INSTALL_FOLDER}\scripts\eclipse\` (.e.g. `C:\Program Files\SharpCap 4.1 (64 bit)\scripts\eclipse\`)
+4. Generate a SharpCap sequence using SharpCap Eclipse Sequencer (toggle the "Also generate Powershell config" checkbox)
+5. Download the `april-2024-solar-eclipse-config.ps1` file and save it to the same directory in step 3 - `{SHARPCAP_INSTALL_FOLDER}\scripts\eclipse\` (.e.g. `C:\Program Files\SharpCap 4.1 (64 bit)\scripts\eclipse\`)
+6. Open SharpCap
+7. Open the SharpCap Eclipse Sequencer script
+8. Run the SharpCap Eclipse Sequencer script
+9. The Powershell script will run alongside the sequencer
+
+*Note: The Powershell script runs separately from the SharpCap Eclipse Sequencer script. Ending the SharpCap Eclipse Sequencer script will not terminate the Powershell script.*
+
+*However, the Powershell script will terminate on its own about 5 seconds after the final scheduled audible alert.*
+
+## Sounds
+
+### List of alerts
+
+The following sound alerts are triggered from the Powershell script:
+
+#### Start
+- Script start
+
+#### C1
+- 60 seconds prior
+- 30 seconds prior
+- 20 seconds prior
+- 10 seconds prior
+- C1
+
+#### C2
+- Refocus telescope (25 minutes prior to C2)
+- Look for Venus (20 minutes, 10 minutes, and 5 minutes prior to C2)
+- 3 minutes prior
+- 2 minutes prior
+- Look for Jupiter (1 minute 30 seconds prior to C2)
+- 60 seconds prior
+- Remove solar filter (33 seconds prior to C2)
+- 30 seconds prior
+- 20 seconds prior
+- 10 seconds prior
+- Diamond ring (8 seconds prior to C2)
+- Baily's beads (5 seconds prior to C2)
+- C2
+
+#### Totality
+- Totality start (4 seconds after C2)
+- Observe the horizon (20 seconds after C2)
+- Look for Pons-Brooks (12P) Comet (50 seconds after C2)
+- Maximum eclipse (middle of C2 and C3)
+    - *Note: This will likely not trigger at the exact maximum eclipse time for your location*
+- Observe the horizon (1 minute 20 seconds after C2)
+- Totality end (4 seconds before C3)
+
+#### C3
+- 60 seconds prior
+- 30 seconds prior
+- 20 seconds prior
+- 10 seconds prior
+- C3
+- Baily's beads (3 seconds after C3)
+- Diamond ring (6 seconds after C2)
+- Replace solar filter (32 seconds after C3)
+- Jupiter disappearing (1 minute after C2)
+- Venus disappearing (5 minutes, 10 minutes, and 20 minutes after C2)
+- Refocus telescope (25 minutes after C3)
+
+#### C4
+- 60 seconds prior
+- 30 seconds prior
+- 20 seconds prior
+- 10 seconds prior
+- C4
+
+#### End
+- Script end
+
+### [TTSMaker](https://ttsmaker.com/)
+The sound alerts were created using [TTSMaker](https://ttsmaker.com/). The following settings were used (as of 03/14/2024):
+
+- Voice: Doris
+- More Settings:
+  - Audio Files Format: wav
+  - MP3 Audio Quality: High Quality
+  - Voice Volume: 150% or 200%
+
+*Note: The other settings were set to the default values.*
+
+### TTSMaker License
+
+As of 03/14/2024, all audio generated by TTSMaker is free for commercial use and is owned by the user. The [TTSMaker commercial license](https://ttsmaker.com/copyright_and_commercial_license_terms/en) states:
+
+> All audio files generated by TTSMaker belong to the user, who has full rights to use, distribute, and disseminate them, including for commercial purposes. However, the user must comply with local laws and regulations and avoid any behavior that may lead to legal disputes.
+
+## SharpCap Sequencer
+
+### Starting the Powershell Script
+
+The following step is added near the top of the SharpCap Eclipse Sequencer script:
+
+```
+RUN PowerShell WITH PARAMS "-NoProfile -ExecutionPolicy Bypass -Command \" & '.\scripts\eclipse\april-2024-solar-eclipse.ps1'\"" WAIT False
+```
+
+## How does it work?
+
+The script is run from the root of the SharpCap install folder.
+
+The Powershell script loads the generated configuration file at the beginning. The configuration file defines various timestamps for audible events throughout the eclipse.
+
+A variety of helper functions are defined to assist with the script execution. The script will sleep until specific times throughout the eclipse. When the sleep timer reaches zero, the next audible alert will trigger.
+
+Timestamps and audio data (file name) are output to the console during script execution.