Watching videos of plays with nflvid

With nfldb and nflvid, it is possible to search for a set of plays, open them as a playlist in a video player and watch the actual game footage of each play. Game footage can be all-22 coach video or the regular broadcast footage.

Here is a small working example that plays each of the 7 plays where Adrian Peterson rushed for more than 50 yards in the 2012 season:

import nfldb
import nflvid.vlc

db = nfldb.connect()
q = nfldb.Query(db)

q.game(season_year=2012, season_type='Regular')
q.player(full_name='Adrian Peterson').play(rushing_yds__ge=50)

nflvid.vlc.watch(db, q.as_plays(), '/m/nfl/coach/pbp')

This simple example demonstrates a lot of power; the entire query interface of nfldb can be composed with a directory of play-by-play footage to watch any subset of plays imaginable.

What is nflvid?

nflvid faciliates the downloading and slicing of NFL game footage from publicly available sources. In particular, everything that nflvid downloads is accessible to the public on NFL's content delivery network powered by Neulion. Note that nflvid does not come with any footage as I will not redistribute any video copyrighted by the NFL.

This means that nflvid's future is uncertain, since the public accessibility of the video could go away. When that happens, and if there are no other public sources, nflvid will be considered a dead project.

In addition to downloading footage, nflvid also downloads meta data (as XML) describing the start times of each play in broadcast and coach video. This data is then used to slice full game video into its component plays. This approach tends to consistently work, although sometimes the start timings in the meta data are off and can lead to incorrect results that are impossible to detect automatically. (Without video analysis.)

Installation

To get the examples in this wiki to work, you must have nfldb installed. You must also install nflvid, which is on PyPI. If you're on Windows, there are special instructions for you on the nflvid wiki.

Installing nflvid can be tricky because it requires run-time dependencies like ffmpeg and rtmpdump. Moreover, downloading huge video files can sometimes fail for unknown reasons. Note that if you want to download coach footage, you need rtmpdump with KSV's patch. Otherwise, coach footage might download successfully but you will be unable to play it. (If someone more knowledgeable than me on video playback would like to add something about why this is, that would be great.) I maintain a fork of rtmpdump with KSV's patch that I try to keep up to date with upstream changes from git://git.ffmpeg.org/rtmpdump.

Since rtmpdump can be tricky to get working, we can verify that nflvid is installed by downloading the first 30 seconds of some broadcast footage:

mkdir -p /home/you/nfl/{broadcast,coach}/{full,pbp}
nflvid-footage --broadcast --dry-run --season 2012 --teams NE --weeks 1 -- /home/you/nfl/broadcast/full

And now you should be able to watch the first 30 seconds:

vlc /home/you/nfl/broadcast/full/2012090904.mp4

If that works, then try downloading the full game (remove the 30 second clip from the previous step first). If you're impatient and want the download to go more quickly, then you can lower the quality to 800 (which is probably just barely watchable). The maximum quality is 4500, which corresponds to 720p HD.

rm /home/you/nfl/broadcast/full/2012090904.mp4
nflvid-footage --broadcast --quality 800 --season 2012 --teams NE --weeks 1 -- /home/you/nfl/broadcast/full

Once the download completes, you can slice the video into play-by-play video files. Namely, there will be a single video file for each play in the game:

nflvid-slice --broadcast /home/you/nfl/broadcast/pbp /home/you/nfl/broadcast/full/2012090904.mp4

You should now be able to watch any of the plays individually:

vlc /home/you/nfl/broadcast/pbp/2012090904/3521.mp4

If you want to try your luck with coach video, then repeat the above steps except remove all occurrences of --broadcast and change your paths from /home/you/nfl/broadcast/... to /home/you/nfl/coach/.... (Note that you can choose any path you like, but it's good to adhere to a sensible convention.)

If you run into problems, please thoroughly read nflvid's README to make sure you haven't missed anything. Then either join us on IRC/FreeNode at #nflgame or open a new issue on nflvid's issue tracker.

Watching footage

Once you have at least one game sliced into its component play videos, you can start trying to filter plays by some search criteria and watch them.

Note though that each play video file has the file path gsis_id/play_id.mp4 (where play_id is padded out to four places, e.g., 0001), so that you could watch a subset of plays using any search mechanism that returns play identifiers found in nflgame or nfldb. However, the machinery to make this convenient for you depends on nfldb.

In particular, we can use the nflvid.vlc module to open any list of plays. The advantage of using nflvid.vlc is that it can write the context of each play as a text overlay of the video using vlc's marquee feature. I personally find this useful for coach footage when there is typically nothing on the screen except for the play.

The main function that you'll use in nflvid.vlc is watch, which takes a database from nfldb.connect(), a list of nfldb.Play objects and a directory containing sliced play video. If successful, it will execute a command that opens vlc with a playlist and all the requisite meta data.

I now leave you with one final example:

import nfldb
import nflvid.vlc

db = nfldb.connect()
q = nfldb.Query(db)

q.game(season_year=2011, season_type='Regular')
q.player(full_name='Wes Welker').play(receiving_yds__ge=90, receiving_tds=1)

nflvid.vlc.watch(db, q.as_plays(), '/m/nfl/coach/pbp')