Introduce Powershell Script and Config Generator

[scottsousa]

Hi @linuxkidd ,

First of all, I wanted to thank you so much for creating this sequencer! I recently acquired astrophotography gear and I'm getting ready to attempt to view and capture the total solar eclipse in April 2024. Your sequencer has been extremely helpful! Here's a bit of backstory for this pull request.

I'm not sure if you prefer a pull request template, but I'll use the following for now. Let me know if you'd like any additional information or if I can clarify anything.

Description

I originally wrote a script for FireCapture. However, I ran into issues with timing and switched to SharpCap. I found your sequencer at the perfect time.

While I was writing my script for FireCapture, I realized it could run external programs. So I decided to write a separate script which would trigger audible alerts at various times throughout the eclipse. This script was written in Powershell. Though I am a web developer by trade, I am by no means an expert in Powershell. However, I was able to get the script to function to my liking.

After finding your sequencer, I thought it would be a good foundation to help make the Powershell script dynamic. This pull request adds all of the Powershell logic. There is functionality to generate a configuration file for the Powershell script based on the sequencer times. The Powershell script is optional as I realize not everyone may have the capability to hear audio alerts on their devices. A checkbox below the "Generate Sequence" button toggles the Powershell script configuration generation.

All of the Powershell script assets are included in a zip archive for easy downloading by users. There's a button at the top of the sequencer to download the zip archive.

I've included a README in the Powershell script directory with more information, including installation details.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Testing

I've tested this alongside my sequencer script a few times now. It does appear to be working as expected. I am planning to test further but I believe it can be considered stable.

Test Configuration:

• Equipment: Mele Quieter3 Mini-PC with Windows 11; tablet to function as "speaker" (see Powershell README) using Windows Remote Desktop

Checklist

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

[linuxkidd]

Hi Scott,
I love this idea! Thanks so much for contributing all this!

A few questions:

• If I recall correctly.. Windows blocks running powershell scripts by default. Is there a command that a would-be user of this new code needs to run before this will work? Or, is that only a restriction of an interactive shell?
• Could you amend your sleepUntilandPlaySound function such that if the time has already passed, the sound playback is skipped?
• How does the script behave if someone restarts the sequence? ( e.g. camera had a usb error and caused the sequence to error, they unplugged / replugged and now need to restart the sequence )

Thanks again!
LK

[linuxkidd]

ok, one other thing.. and this is a big one..

Would you be opposed to switching this to being all done from inside the Sequencer?

The timing could easily be managed there, and then the following could be used to play the sounds:

RUN PowerShell WITH PARAMS "-c (New-Object Media.SoundPlayer 'c:\Windows\Media\ding.wav').PlaySync();" WAIT False

I'm not sure what using powershell for an entirely parallel execution adds that couldn't be achieved using this approach?

Thanks,
LK

[scottsousa]

Hi @linuxkidd ,

These are some great questions and thoughts! Let me put some time into refactoring the logic this week and I'll get back to you with answers and an update.

Thanks,
Scott

[scottsousa]

Hi @linuxkidd ,

I have thought about this further. I will answer your questions and then I add some thoughts and questions too.

1. If I recall correctly.. Windows blocks running powershell scripts by default. Is there a command that a would-be user of this new code needs to run before this will work? Or, is that only a restriction of an interactive shell?

This is a great question. I believe you are correct but there is also an exception. The
-ExecutionPolicy Parameter can be used to bypass the default execution policy. I believe that setting this to a value of Bypass should theoretically allow the script to run without any issues. For what it's worth, I've only tested this script with admin accounts on my devices so I'm not 100% positive. I could do further testing if need be.

2. Could you amend your sleepUntilandPlaySound function such that if the time has already passed, the sound playback is skipped?

Yes this is definitely possible.

3. How does the script behave if someone restarts the sequence? ( e.g. camera had a usb error and caused the sequence to error, they unplugged / replugged and now need to restart the sequence )

With the modification above, the script should pick up where the user left off. Currently the script does loop through playing all of the previous sounds until it reaches the last sound. Right now this isn't ideal as the script hangs slightly in some cases. The change above should fix it this.

4. Would you be opposed to switching this to being all done from inside the Sequencer?

I am certainly not opposed to this as I think it could help ease the burden for anyone using this feature. This is where my thoughts and questions originate from.

---

I'm not sure what using powershell for an entirely parallel execution adds that couldn't be achieved using this approach?

When I originally started developing this script, I chose to separate it from FireCapture due to minimal amount of functionality the script editor there. I had to run a batch script to trigger the Powershell script. When I ported this over to SharpCap, I used the same thought process because the script was already built. However, your ideas got me thinking and I do have a potential revised approach in mind.

Today I was able to create a series of Powershell commands which, when passed to the RUN <Program> WITH PARAMS step, can create both a Windows notification (more on this later) and also speak on the fly using text-to-speech (TTS). This should allow for SharpCap to control everything but I have some concerns.

1. The SharpCap Sequence Editor is just that, a sequential (linear) execution of steps, in order as they appear. That being said, I am not sure how feasible it would be to add the Powershell commands in various locations with the current sequencer (your script). I have seen that you've added some safeguards to wait until specific times or execute steps only after certain times. It doesn't appear that additional steps can run when the SharpCap Sequence Editor is waiting. I would love to get your thoughts on this, as you likely gave a better understanding of the SharpCap Sequence Editor than I do. What do you think about the feasibility of modifying the sequencer (your script) to account for all of the different alerts and alert times?

For reference, the Sequence Editor documentation states:

These tasks are achieved by constructing an imaging sequence that consists of running a number of individually relatively simple steps in order.

2. Even though the RUN <Program> WITH PARAMS step has a flag to indicate if SharpCap should wait until finished (and this is set to FALSE currently), I am wondering if triggering some of the Powershell commands might affect captures in any way? For example, I have created alerts for the diamond ring, Baily's beads, totality, maximum eclipse, comet Pons-Brooks (12P), etc...These are triggered while the respected captures are running. I think we'd need to inject the Powershell commands between capture steps. I'd like to hear your thoughts. Do you think this would interfere with captures at all?

3. If we do decide to add the Powershell commands to the sequencer (removing the Powershell script), we'll have to deal with at least a flash of the console window. Unfortunately there's an older bug which has not been fixed yet. This means that, even if we run the command with -WindowStyle Hidden, the console window opens briefly.

---

To summarize, whatever we end up deciding on, I can work on the following as needed:

1. Remove the .wav sound files as TTS should work on Windows 10/11 according to this reference. I believe .NET 3.0 or higher will be required but this should already be included in Windows 10/11.

2. Modify the Powershell script to skip sound playback if restarted

3. Assist with creating Windows notifications via a Powershell command. I ran into an issue on one of my devices, with Windows 11 Home, where msg.exe doesn't exist so the SharpCap sequence throws an error. I will raise a separate issue for this.

Example notification from Powershell:

---

I hope I'm not overthinking this too much. Looking forward to your thoughts.

[linuxkidd]

What do you think about the feasibility of modifying the sequencer (your script) to account for all of the different alerts and alert times?

• It's certainly do-able.

I am wondering if triggering some of the Powershell commands might affect captures in any way?

• I do suspect there will be a slight delay just from spawning powershell, even with WAIT FALSE. I think this warrants more testing.

we'll have to deal with at least a flash of the console window.

• Ya, I noticed this in my testing too.. although I hadn't researched to find the -WindowStyle Hidden feature, even with its flaw.

TTS should work on Windows 10/11

• Should we worry about a delay in the spoken prompt due to the TTS processing? If so, does it make more sense to leave the generated wavs as an option?

The further we get down this ( seaming simple ) path, the more I lean toward using the Python scripting integration in SharpCap instead of the sequencer. There's just so much more control, including options for parallel executions, etc. The downside is... the learning curve and troubleshooting that has to occur in the next few (short) weeks.

[scottsousa]

Thanks @linuxkidd ! I know what you mean. Time isn't really on our side right now.

Here's what I'm thinking. I'll plan to refactor some of my logic while retaining the Powershell script because I know that is working for me right now. I'll plan to commit some updates here soon. I'll likely keep the .wav files as a backup option in case anyone would like to use them. In my testing, both versions (.wav and TTS) take about 2 seconds to execute from the time they are called from SharpCap. I did not notice any discernable processing time with TTS. With the Powershell script running in parallel, the ~2 second delay shouldn't be an issue.

I'll also plan to start a new pull request to attempt to have the SharpCap Sequence Generator manage the timing and trigger the alerts. I think it'll be easier for me to manage this in a separate pull request because it's involves a different approach.

I'll be in touch!

[scottsousa]

Hi @linuxkidd ,

I've been working on refactoring my Powershell script logic and I think it's in a pretty good place now. I feel it's more robust and it also gracefully handles restarts. I will be running through some real-world tests today to ensure the alerts are triggered at the proper times.

Here's a list of updates since my last commit:

• Add section for Powershell script configuration to script HTML file
• Add the following Powershell script configuration settings: generate (update to a dropdown), display windows notifications (Yes/No), sound type (TTS or WAV)
• Adjusted Powershell variable names for consistency
• Created various Powershell helper functions
• Converted sleepUntilandPlaySound() to sleepUntilAndThenTriggerAlert() - sleep, show windows notification, play sound
• Converted all Powershell sound alert details into variables and added these to the Powershell configuration file
• Added logic to skip sleeping and playing sound alerts if the timestamp is in the past
• Added various information statements to the console during script execution
• Updated code formatting and comments

I still need to update the documentation and add logic to save the settings to localStorage/the encoded URL parameters.

There is likely a better way to define all of the configuration parameters/variables. I'm open to ideas if you have any. I wanted most everything to be in the config file to allow users to customize to their liking.

[linuxkidd]

Hi @scottsousa
I love it... but have made some tweaks..

Highlights:

• Made the list of notifications an array of dictionary entries ( array of associative arrays )
• Converted the calling of the notifications into a loop
• Made the TTS the only option ( minimizing download content size for end users )
• Made it so that even with no 'partial' collection, the PS Script can still generate for events +/- 299 seconds of C2/C3 times.
• Random clean-up of variables and logic in index.html
• Changed the -WindowStyle from Hidden to Minimized to allow easier termination should things go sideways.
• Added powershell params to localStorage / url hash

Please check the powershell branch. It can be tested using the htmlpreview link

I hope you don't mind me mangling your code.. 😁

ToDo:

• Tweak the instructions / download script link in index.html

[scottsousa]

Hi @linuxkidd ,

Thanks! This is really cool. I don't mind at all.

I will plan to review the code changes and test as soon as I have a moment.

[linuxkidd]

Hi @scottsousa ... another big change!

I moved all of the notifications array into the main eclipse script, and configured the script to accept params on the command line.

So now, it's fully self contained and just gets called from the sequence with no external config file needed!

[scottsousa]

@linuxkidd That's awesome! Great work. Thanks for bringing this to the next level!

I will plan to test tonight if possible.

I did notice one issue when I pulled the upstream changes to my local computer. Unfortunately the fetch() call isn't working due to CORS. Would you be opposed to changing button to a link and instructing users to right click and save? If not, I could work on that logic. We could even likely only change it to a link when the file is loaded locally.

[linuxkidd]

Hi @scottsousa ,
The CORS block only occurs when using local serving of the file ( like, file:// ). Once it's on the server, it works fine.

The branch can be tested from a public server here:
https://htmlpreview.github.io/?https://raw.githubusercontent.com/linuxkidd/SharpCap-Eclipse-Sequencer/powershell/index.html

Once someone has the file saved locally, and/or saves the HTML to launch in their browser, they should already have the powershell script and won't need the link to work then ( at least, that's my expectation ).

[linuxkidd]

Closing this pr, further updates / discussion via pr #5