Package nflvid
[frames] | no frames]

Package nflvid

source code

Introduction

A simple library to download, slice and search NFL game footage on a play-by-play basis.

This library comes with preloaded play-by-play meta data, which describes the start time of each play in the game footage. However, the actual footage does not come with this library and is not released by me. This package therefore provides utilities to batch download NFL Game Footage from the original source.

Once game footage is downloaded, you can use this library to search plays and construct a playlist to play in any video player.

Classes
  Play
Represents a single play with meta data that ties it to game footage.
  PlayTime
Represents a footage time point, in the format HH:MM:SS:MM
Functions
 
footage_url(gobj, quality='1600') source code
 
footage_full(footage_dir, gobj)
Returns the path to the full video for a given game inside an nflvid footage directory.
source code
 
footage_plays(footage_play_dir, gobj)
Returns a list of all footage broken down by play inside an nflvid footage directory.
source code
 
unsliced_plays(footage_play_dir, gobj, dry_run=False)
Scans the game directory inside footage_play_dir and returns a list of plays that haven't been sliced yet.
source code
 
slice(footage_play_dir, full_footage_file, gobj, threads=4, dry_run=False)
Uses ffmpeg to slice the given footage file into play-by-play pieces.
source code
 
slice_play(footage_play_dir, full_footage_file, gobj, play, max_duration=15)
This is just like slice, but it only slices the play provided.
source code
 
download(footage_dir, gobj, quality='1600', dry_run=False)
Starts an ffmpeg process to download the full footage of the given game with the quality provided.
source code
 
plays(gobj)
Returns an ordered dictionary of all plays for a particular game.
source code
 
play(gobj, playid)
Returns a Play object given a game and a play id.
source code
Variables
  __package__ = 'nflvid'
Function Details

footage_full(footage_dir, gobj)

source code 

Returns the path to the full video for a given game inside an nflvid footage directory.

If the full footage doesn't exist, then None is returned.

footage_plays(footage_play_dir, gobj)

source code 

Returns a list of all footage broken down by play inside an nflvid footage directory. The list is sorted numerically by play id.

If no footage breakdown exists for the game provided, then an empty list is returned.

unsliced_plays(footage_play_dir, gobj, dry_run=False)

source code 

Scans the game directory inside footage_play_dir and returns a list of plays that haven't been sliced yet. In particular, a play is only considered sliced if the following file is readable, assuming {playid} is its play id:

   {footage_play_dir}/{eid}-{gamekey}/{playid}.mp4

All plays for the game given that don't fit this criteria will be returned in the list.

If the list is empty, then all plays for the game have been sliced. Alternatively, None can be returned if there was a problem retrieving the play-by-play meta data.

If dry_run is true, then only the first 10 plays of the game are sliced.

slice(footage_play_dir, full_footage_file, gobj, threads=4, dry_run=False)

source code 

Uses ffmpeg to slice the given footage file into play-by-play pieces. The full_footage_file should point to a full game downloaded with nflvid-footage and gobj should be the corresponding nflgame.game.Game object.

The footage_play_dir is where the pieces will be saved:

   {footage_play_dir}/{eid}-{gamekey}/{playid}.mp4

This function will not duplicate work. If a video file exists for a particular play, then slice will not regenerate it.

Note that this function uses an eventlet green pool to run multiple ffmpeg instances simultaneously. The maximum number of threads to use is specified by threads. This function only terminates when all threads have finished processing.

If dry_run is true, then only the first 10 plays of the game are sliced.

slice_play(footage_play_dir, full_footage_file, gobj, play, max_duration=15)

source code 

This is just like slice, but it only slices the play provided. In typical cases, slice should be used since it makes sure not to duplicate work.

This function will not check if the play-by-play directory for gobj has been created.

max_duration is used to cap the length of a play. This drastically cuts down on the time required to slice a game and the storage requirements of a game at the cost of potentially missing bigger plays. This may get smarter in the future. Set max_duration to 0 to impose no artificial cap.

download(footage_dir, gobj, quality='1600', dry_run=False)

source code 

Starts an ffmpeg process to download the full footage of the given game with the quality provided. The qualities available are: 400, 800, 1200, 1600, 2400, 3000, 4500 with 4500 being the best.

The footage will be saved to the following path:

   footage_dir/{eid}-{gamekey}.mp4

If footage is already at that path, then a LookupError is raised.

A full game's worth of footage at a quality of 1600 is about 2GB.

plays(gobj)

source code 

Returns an ordered dictionary of all plays for a particular game.

The game must be a nflgame.game.Game object.

If there is a problem retrieving the data, None is returned.

If the game is over, then the XML data is saved to disk.

play(gobj, playid)

source code 

Returns a Play object given a game and a play id. The game must be a nflgame.game.Game object.

If a play with the given id does not exist, None is returned.