ghjwp7 / yzoomy Goto Github PK

By James Waldby - 11 April 2020 - Copyright © 2020 - Offered without
warranty under GPL v3 terms as at http://www.gnu.org/licenses/gpl.html

This README describes some Bash shell scripts, yzoomy-menu, yzoomy,
club-yume-zoom, and cczoomy. The scripts allow timing speeches while
automatically changing backgrounds for Zoom (or similar) to Green,
Yellow, Red at intervals.  The yzoomy-menu script presents a simple
text-based menu with choices of a few speech lengths suitable for
contests, plus names of contestants.  (You will need to edit names of
contestants into the script.)  The cczoomy script provides countdown,
timesho, and annotate functions.  The club-yume-zoom script makes a
clickable yume menu; eg see image menu-cyz.png.

Repository Contents -- Besides the scripts, this repository contains a
number of small images suitable for virtual backgrounds.  You can use
these images, or make your own, or download larger, fancier, branded
images from Toastmasters International at the following URL:
<https://www.toastmasters.org/resources/Timer%20Zoom%20Backgrounds>.

Operational Requirements --
yzoomy-menu depends on yzoomy for timing and image-changing functions.
In its operation, yzoomy requires a calibration file, which can be
created using a choice from yzoomy-menu's menu, as described later.
When used with Zoom, yzoomy also requires that the Zoom virtual
background setup window remain visible (on top) in its calibrated
location during speech timing; else, mouse clicks will be ineffective.

Adding names of contestants --
Using a plain-text editor, change yzoomy-menu or club-yume-zoom by
substituting actual names in place of "contestant name1" etc.  You can
remove extra such entries or add more, as you like.

Operation Examples --
Start yzoomy-menu with a command like ./yzoomy-menu.  Then
select choices by entering their numbers and pressing enter.

Example 1: To select the contestant who is named in item 13 and time
their 5-7 minute speech: Press 13, enter to select the contestant.
Press 3 (Time 5-7) to select the 5-7 range.  When the speaker starts,
press enter to start timing.  Press 1 (Stop), to have it ready; and
when the speaker finishes, press enter to stop timing.  The starting
and ending times for the speech will appear intermixed with menu
prompts, and will also be written to a file, which can be listed out
by pressing 4 (List times), enter.

Example 2: To time an anonymous minute for judges to work, press 5
(Anon 1-1), enter.  After the yzoomy script turns on the Red light,
press 1, enter to stop timing.  "Anon" start and stop times don't get
listed in the times file.  And if you don't select a contestant name
after that Anon time, subsequent times won't be filed either (will
just list on the script console) until you do so.  You can select a
name during a speech if you need to, which will cause the elapsed time
to be filed when you Stop the timing.

Timing Sequences --
After you choose a speech time and start it going, the `Timing`
picture should appear during the interval before Green appears.  When
the Green time arrives, yzoomy uses xdotool to move the mouse cursor
to the green image and click it, raising a green virtual background.
It acts similarly when Yellow or Red times arrive, if the speech lasts
that long.  When you choose Stop, the End picture will get clicked on,
and elapsed time (difference between ending time and starting time)
will display and will be written to a file if a contestant name has
been given.

Note, yzoomy moves the cursor out of the menu window each time it
selects a new background image, and should return it to the menu
window a few milliseconds later.  However, it's possible for
interference to occur and you may sometimes need to move it back with
the mouse.

Purpose and use of yzoomy --
From time to time the yzoomy-menu script calls functions in the yzoomy
script: speech, ending, and CalibrateColors.  yzoomy provides those
functions and other utility functions, to allow automatic clicking at
appropriate times on Green, Yellow, or Red pictures in the Zoom
Virtual Background setup box.

Functions of yzoomy also can be called from the shell command line
(instead of as choices from yzoomy-menu).  The command-line examples
below (where <green> and <red> are numbers of minutes) illustrate five
things:  
(1) Start a timed speech, with a start line written to file;
(2) end a speech, and write elapsed time to file;
(3) start timing an interval, unfiled;
(4) end timing, unfiled; and
(5) start a 60-second countdown timer that updates each 10 seconds

  (1)       yzoomy speech <green> <red> <name-of-speaker> &
  (2)       yzoomy ending <name-of-speaker>
  (3)       yzoomy speech <green> <red> &
  (4)       yzoomy ending
  (5)       cczoomy countdown 60

Calibrating coordinates --
yzoomy provides a calibration function, CalibrateColors.  When it
runs, it will prompt you to move the mouse cursor in turn onto
appropriate pictures among the choices in the Zoom Virtual Background
setup box.

Before calibrating, follow Zoom procedures for adding images, like
G.png, Y.png, etc. to Zoom's Virtual Background setup window.  yzoomy
cannot click on images that aren't on the screen.  If extra images
push desired images out of view or make them not all visible at once,
then change the order of images to make all necessary images visible
at the same time.  For example, remove some extras; install desired
images; reinstall extras if needed; finally, scroll the selector pane
to make desired images visible.  [Note: Zoom copies images into
~/.zoom/data/VirtualBkgnd_Custom and makes up its own arbitrary
UUID-formatted names for the files.  The cczoomy script assumes the
most recent file in that directory is the option file and also assumes
it is ok to Overwrite the most recent file whenever it likes.]  Note,
if you find better alternatives for operations used in these scripts,
please let me know.

In calibration, after a prompt for an item appears, you have three
seconds to move the mouse to the item.  Change the script if you need
more time.  If a prompt occurs for an item you don't have or need,
either change the script, or click on anything, or add the item; then
recalibrate.  If you intend to use the cczoomy script, select a
don't-care image as an overwritable `option` background.


Other software required --
These scripts uses GNU sleep for partial-second sleeps.  If your sleep
command only has whole seconds, replace sleep 0.3333 or similar with
sleep 1.  This script uses xdotool to get screen locations of buttons
or images and to produce mouse clicks on those buttons or images.  If
you don't have xdotool install it via sudo apt-get install xdotool or
sudo yum install xdotool, or rewrite the script to use some other
tool.