User manual - ovscout2 • ovscout2

Introduction

ovscout2 is a free, open-source R/Shiny app for scouting volleyball matches. It provides industry-standard dvw files that can be used with the openvolley suite of R packages, or with any other volleyball analytics software that takes dvw files as inputs.

The app requires that you have a video of the match from a fixed view point (i.e. the camera does not move for the duration of the match). Such videos are usually taken from the “scout viewpoint” — behind one end of the court, at a reasonable height so that the entire court is clearly visible and players on court do not tend to occlude each other.

The app is writen in R, but you do not necessarily need to be an R user to be able to use it. We provide script files to launch the app from the command line — see the Standalone section below for installation and startup.

Installation

The app can be run on Windows, Linux, or Mac systems. It is possible to run the app on a laptop or desktop and connect to it with a tablet or similar touch device to do the actual scouting. See Device considerations below.

You need to be online for installation. The app initially needs to download and install some additional R packages (quite a few, in fact). Once the app has been installed and run once, it can be used offline thereafter if necessary.

Also see the “Other system utilities” section, below.

Standalone

The standalone installer allows you to run the app without having to do anything in R.

Windows

Download https://github.com/openvolley/ovscout2/releases/download/v0.1.0/ovscout2-win-x64.zip and unzip it to a convenient location.
Run the ov_scouter.bat or ov_scouter_demo.bat file. The first run will take quite some time, because it will install a number of additional R packages. Subsequent startups will be much faster (it checks for updates on each startup, so might reinstall some packages on occasion).

Linux/Mac

Install R, following https://cran.r-project.org/
On Mac, you will also need to install XQuartz: https://www.xquartz.org/
Optionally install ‘Other system utilities’ (see below)
Download https://github.com/openvolley/ovscout2/releases/download/v0.1.0/ovscout2-unix-x64.zip and unzip it to a convenient location.
Run the ov_scouter or ov_scouter_demo script. The first run will take quite some time, because it will install a number of additional R packages. Subsequent startups will be much faster (it checks for updates on each startup, so might reinstall some packages on occasion).

Installation from R

Install R and RStudio.
Optionally install lighttpd (see ‘Other system utilities’ below)
From RStudio:

install.packages("ovscout2", repos = c("https://openvolley.r-universe.dev",
                                       "https://cloud.r-project.org"))

## or

## install.packages("remotes") ## if needed
remotes::install_github("openvolley/ovscout2")

Other system utilities

Two other system utilities are recommended but not required. Note that the standalone Windows bundle already includes these utilities — no further action is needed in that case.

pandoc is required for generating match reports from scouted files. Install following https://github.com/jgm/pandoc/blob/master/INSTALL.md. If not present, the report generation menu item won’t be shown. If you are starting the app from RStudio, you do not need to install pandoc because RStudio comes bundled with its own copy.
lighttpd is a lightweight web server that is used to play the match video (when using a local video file). Install (from within R, on Windows only) using ovscout2::ov_install_lighttpd() or manually from http://lighttpd.dtech.hu/ (for Windows) or via your package manager for other operating systems (see https://redmine.lighttpd.net/projects/lighttpd/wiki/GetLighttpd). If lighttpd is not installed, the app falls back to servr but this is a little slower and less responsive than lighttpd.

Startup and usage

Some of startup options are the same regardless of whether you are using the standalone version or starting the app from within R:

the “season directory” is a folder containing dvw files from other matches. If you are scouting a new match and you provide a season directory, you can choose teams from other matches for the new match. This saves having to re-enter team and player details. The season directory will also be used as the starting point when selecting a video file
the video file is required
you can also optionally provide a .dvw or .ovs file (i.e. a partially-scouted file that you wish to continue scouting). If you do not provide a dvw file, the app creates a new, empty match file.

Startup — standalone

Run the ov_scouter.bat (Windows) or ov_scouter (Linux/Mac) script. It will prompt you for a season directory, dvw file, and video file. The season directory and dvw file are optional (a new match file will be created if no dvw is provided) but the video is required.

Options controlling the app behaviour and scouting preferences can be changed via the “Preferences” button in the app.

Startup — from R

In each session you first need to load the ovscout2 package:

library(ovscout2)

Then start the app. You can start it with no arguments:

ov_scouter()

… and it will prompt you (as for the standalone version) for a season directory, dvw file, and video file. The season directory and dvw file are optional (a new match file will be created if no dvw is provided) but the video is required.

You can optionally provide those arguments explicitly. To start a new match for a certain video file, using teams from already-scouted matches in your season directory, you could do:

ov_scouter(video_file = "/path/to/video.mp4", season_dir = "/path/to/season_dir")

If you have already partially-scouted a match and saved that file, you can re-start scouting:

ov_scouter("/path/to/saved_file.ovs")

(In this case you do not need to provide the video file path, because that is saved within the .ovs file.)

Device considerations

The scouting process involves clicking the location of actions on court, and so a touch screen device (ideally with stylus) is recommended. It is possible to run the app on a laptop or desktop and connect to it with a tablet or similar touch device to do the actual scouting. In this case you would start the app from R on the main device using the host and launch_browser options:

ov_scouter(..., host = "192.168.1.11", launch_browser = FALSE)

where 192.168.1.11 is the IP address of the main device. You should see a message similar to (the port number on the end will vary):

Listening on http://192.168.1.11:5017

Open a browser on the tablet and enter http://192.168.1.11:5017 in the address bar.

Preferences

There are a number of options available that alter the behaviour or appearance of the app. These can be set (if you are starting the app from within R) via parameters to the ov_scouter() function. Most can also be set via the “Preferences” button in the app (others will be added in due course):

auto_save_dir is a directory into which the scouted file will be saved (in .dvw format) after each rally. You can use this to e.g. provide live file updates to be used by the coaching bench
scoreboard - show the scoreboard in the top right-hand corner of the video screen (true by default)
ball_path - show the ball path on the court diagram (false by default, because it slows the app down a little)
review_pane - show the video review pane on each data entry popup (true by default)
playlist_display_option - what to show in the plays table? Either “dv_codes” (scouted codes) or “commentary” (a plain-language interpretation of the touches)
shortcuts - a named list that defines the keyboard shortcuts used in the app

Preferences controlling the scouting conventions can similarly be set via the ov_scouting_options() function or the “Preferences” button. These include:

end_convention determines whether you are treating the end coordinate of an attack or serve as the actual end location (i.e. where the ball contacted the floor or out of bounds area), or the intended end location. The actual might differ from the intended if there is a block touch or the ball hit the net. If ‘actual’, and a block touch is recorded, then the end location of the attack will not be used for the dig location (the dig location will be missing).
transition_sets. If FALSE, then sets in transition are not scouted. After entering an attack end location (and play continues) the next click will be for the counterattack start location, with no set scouted in between.

Starting a new match

To scout a new match, start the app with the corresponding video file, then:

Define the court reference via the “Court reference” button. This requires you to click on the four corners of the court in the video image, so that the app can map clicks in the video to real-world court coordinates
Enter the match details via the “Edit match data” button (match date, venue, scout name, etc)
Define the teams playing in the match. If you have provided a season directory (with existing .dvw or .ovs files in it) you can choose from the teams in those files. Otherwise you can enter new teams
Enter the team lineups for set 1, including the libero(s) for each team. If two liberos are entered, then the app will assume that the first libero is on court during serve reception (i.e. the “passing” libero) and the second libero is on court while serving (the “defending” libero). If the team has two liberos but only one takes to the court per set, then just enter the libero who is actually going to play in that set

Scouting

The scouting process is a guided one. Each contact is marked by clicking on the video at the time and point of contact, with the point of contact being the point on the floor directly below the ball as it is being played. This will often be between the player’s feet as they dig or set the ball, or below them if they are jumping to spike.

Start by:

checking that the orientation of the court diagram (top right) matches the video. Swap it using the ⇵ button if required
check that the correct team is serving (indicated by the white circle in the court diagram). Swap with the “Change serving team” button if required
unpause the video. The number of the serving player and their serve type (float/jump/etc) will be shown below the video panel. You can change the serve type before the serve, if you can see that it is wrong

First contact (serve)

click the serve (the point on the court below the ball) as it happens. The video will continue playing
click the reception location (if the ball is touched by a receiver) OR the point where the ball lands/hits the net (if it is an untouched ace or an error). The video will automatically pause and a dialog will pop up allowing you to select the receiving player and serve outcome (serve error, ace, or reception in play). You can also adjust the serve type if it was incorrect. In some cases it isn’t clear at this point if the serve was an ace or a “reception in play” (e.g. a shanked pass that players are chasing down, but we haven’t yet seen if they are successful). In this case click “Reception in play”. It can be adjusted to an “Ace” at the next step, if necessary

If you did not click the reception location correctly, or for some other reason want to go back and try again, click “Cancel and rewind”. Otherwise click “Continue” and the video will resume playing.

Second contact (set)

click the location of the set (or second-contact action if it was something else, such as a setter tip. Remember that this is the point on the ground directly below the ball, not the ball itself). The video will pause and a data entry dialog will pop up
choose the correct second-contact action (by default this is a “Set” but it can also be a set error, setter tip, second-ball attack, or freeball over. If the reception turned out to be an error here (serve ace, with no second contact to scout) you can also select that here
check the pass quality. It will have been automatically given a grade, but in some situations you might need to override the automatic assessment
if the pass was an overpass, you can assign the appropriate opposition action (dig, dig error, or overpass attack) and player

The second contact is by default a set, by the assigned setter on court. Once you are comfortable with the scouting process, and you see a second contact set by the setter, you can hold down shift while clicking the second contact. This causes the app to enter a set action (by the setter) with the automatically-assigned pass quality, without stopping the video or showing the data entry dialog, which makes this part of the scouting faster.

Similarly to a reception error, in some cases it isn’t immediately clear if the set is an error or not (e.g. an unhittable set, or a delayed double-contact call by the referee). Scout this as a set (by the appropriate player) and it can be converted to a set error in the next step if necessary.

Third contact (attack)

The third contact is most commonly an attack (but can also be a freeball over or set error, or a play by the opposition on an overpass/overset.

click the contact location (remember that this is the point on the ground directly below the ball, not the ball itself). The video will pause and a data entry dialog will pop up

If it is an attack:

enter the attacking player and either the attack combination code (if you are scouting with combo codes) or tempo
optionally (but recommended) enter the number of blockers on the attack

Otherwise enter the appropriate action and player.

Attack end point

After an attack or freeball over, click the end point. If you are scouting with “actual” end convention (see Preferences) then this is the point where the ball lands, or the point on the court directly below the ball when it is played. If end convention is “intended”, this is the point where the attacker intended to hit the ball.

Enter the appropriate details. An attack kill, dig or dig error can also involve a block touch — this can be recorded (see “With block touch by player …”).

If the attack was dug (i.e. play continues) and you do not care about scouting digs, you can shift-click the attack end point and the app will record the end point of the attack without showing a popup dialog. This is faster, but note that no dig will be scouted, and no block touch can be entered.

Transition play

Scouting now continues until the point ends, with attacks, digs, and other contacts being recorded. By default, sets in transition are not scouted (except for set errors, since a set error will end the rally). After an attack, we record the dig location and then straight to the counter-attack location, with no intervening set being scouted. You can choose to include transition sets if you wish (see Preferences to change this behaviour) but there is not a huge practical advantage in doing so. It does not enable much more in terms of analytics, but takes extra time to scout, so transition sets are disabled by default.

End of the point

The point can be ended by entering a terminal action (kill or error), or if the point ends in a way that doesn’t fit nicely with the available options, you can pause the video (press “q” or the pause button) and choose “Won current rally” for the appropriate team.

End of set

When the set concludes, it will prompt you to confirm whether it is the end of the set. Confirm the end of the set and then enter the lineups for the next set ready to start scouting that one.

Timeouts and substitutions

Pausing the video (press “q” or the pause button) will bring up a dialog that allows you to enter a timeout or substitution, or change the setter on court for a given team (e.g. if the team is playing a two-setter system, you will need to change the setter on court each time the setters swap).

Frequently asked questions

What’s the difference between a .ovs file and a .dvw file?

The .ovs file format is used internally by the app to store a match as it is being scouted. It is similar to a .dvw file, but contains more information than a .dvw file and in a different format. If you save a partially-scouted match and come back to it later to continue scouting, use the .ovs file format. (You can continue scouting from a partially-scouted file in .dvw format, but the “undo” functionality is limited).

If you have finished scouting a match and wish to use that match file in other analysis software (including the openvolley R packages), export it to dvw format and use that.

The video is black and the app says “Wait for the video media information to be loaded”

ovscout2 relies on the browser to do the actual video playback, but some videos are not compatible with web browsers. *.MOV files recorded with iPhones/iPads are known to suffer from this problem. Try playing the video file directly in the web browser (open a new tab and drag the video file onto it). If the video doesn’t play in the new browser tab, you will need to re-encode the video into a browser-compatible format (try https://handbrake.fr/, for example).