/ 
Linux-DVB-DVBT-Advert-0.04
River stage one • 1 direct dependent • 1 total dependent
/ Linux::DVB::DVBT::Advert

NAME

Linux::DVB::DVBT::Advert - Advert (commercials) detection and removal

SYNOPSIS

	use Linux::DVB::DVBT::Advert ;
  
	# Read advert config info
	my $ad_config_href = ad_config() ; 

	# skip advert detection
	if (!ok_to_detect($results_settings_href))
	{
		print "Skipping advert detection...\n" ;
		exit 0 ;
	}

	# detect
	my $settings_href = {
		'debug' => $DEBUG,
		'progress_callback' => \&progress,
	} ;
	$results_href = detect($file, $settings_href, $channel, $ad_config_href, $det) ;

	# .. or re-use saved deetction
	$results_href = detect_from_file($detect_file) ;
	
	# analyse
	my @cut_list = analyse($file, $results_href, $ad_config_href, $channel, $csv, $expected_aref, $settings_href) ;
	
	# remove adverts
	ad_cut($file, $cutfile, \@cut_list) ;
	
	# ..or split file at advert boundaries
	ad_split($file, $cutfile, \@cut_list) ;

DESCRIPTION

Module provides the interface into the advert (commercials) detection and removal utilities. As well as an underlying transport stream parsing framework, this module also incorporates MPEG2 video decoding and AAC audio decoding (see Linux::DVB::DVBT::TS module for full details).

Basic Operation

Advert removal is split into 2 phases: detection and analysis. The detection phase processes the video and audio data, producing raw statistics for each video frame (I effectively sunchronise the audio frames and group their results into video frames). These raw statistics are then post-processed in the analysis phase to determine the (hopefully!) actual location of the commercial breaks.

The detection phase is completely run in C code under XS; the analysis phase is completely run in Perl.

Settings

Settings are passed into the routines via a HASH ref. Settings also come from the default set, and from any config file parameters. Please see "Settings" in Linux::DVB::DVBT::Advert::Config for full details.

In general, you will probably only be interested in changing the analysis settings to tweak the results for a particular channel (or to completely disable advert detection for a channel). The detection parameters seem to be pretty good for all channels.

Results Files

The output from each phase can be stored into files for later re-use or analysis. The detection phase output file can be reloaded and passed to the analyse phase multiple times to try out different analysis settings. The analyse phase output can be plotted to show the effectiveness of the algorithms used.

Functions

ad_config( [$search] )

Get advert configuration information from a config file. Optionally sets the search path - which is an ARRAY ref containing the list of directories to search.

Returns the HASH ref of advert settings.

ad_debug($level)

Set debug level.

ad_config_search( [$new] )

Get/set search path for advert config file.

Returns the current setting.

channel_settings($settings_href, $channel, $ad_config_href)

Returns a HASH ref containing advert settings from the config file (if available).

The $settings_href settings HASH ref contains any new settings that the user wishes to use, overriding global values or config file values.

The $ad_config_href parameter is expected to be the tuning info HASH ref read in using Linux::DVB::DVBT::Advert::Config::read_dvb_adv($dir). It is used to set any settings read in from the default config file.

detect($src, $settings_href, $channel, $ad_config_href, $detect)

Read the source TS file $src and return a HASH containing the detection statistics for each frame.

The $ad_config_href parameter is expected to be the tuning info HASH ref read in using Linux::DVB::DVBT::Advert::Config::read($dir). It is used to set any settings read in from the default config file. If it is undef then a default search path is used.

The $settings_href settings HASH ref contains any new settings that the user wishes to use, overriding global values or config file values.

The optional $channel parameter is used to specify the TV channel that the video was recorded from. This then allows the config fiel to contain channel-specific settings which are used in the detection. If no channel is specified (or the channel name is not found in the config file) then just default settings are used.

If the optional $detect parameter is specified then the results are saved into the text file named by the parameter

detect_from_file($detect)

Read the text file named by the $detect parameter and return a HASH containing the detection statistics for each frame. All settings are read in from the detection file (but any settings may be overridden in the "analyse($src, $results_href, $ad_config_href, $csv, $expected_aref, $settings_href)" function).

read_expected($src)

Read in expected results file. Used more for debug / display purposes.

analyse($src, $results_href, $ad_config_href, $channel, $csv, $expected_aref, $settings_href)

Process the results to create a cut list for the video using the results gathered by "detect($src, $settings_href, $ad_config_href, $detect)" or "detect_from_file($detect)". Results from detection are stored in the $results_href HASH ref.

The $ad_config_href parameter is expected to be the tuning info HASH ref read in using Linux::DVB::DVBT::Advert::Config::read($dir). It is used to set any settings read in from the default config file. If it is undef then a default search path is used.

The optional $channel parameter is used to specify the TV channel that the video was recorded from. This then allows the config fiel to contain channel-specific settings which are used in the detection. If no channel is specified (or the channel name is not found in the config file) then just default settings are used.

Optionally specify a filename using $csv to save the analysis results in a comma-separated output file (from use in GUI viewing tool).

Optionally specify an ARRAY ref of expected results (read in using "read_expected($src)") to allow the GUI viewing tool to mark the positions of the expected program breaks.

Optionally specify extra settings in order to override the defaults and those used during detection.

ad_cut($src_file, $cut_file, $cut_list_aref)

Cut the $src_file at the points specified in the ARRAY ref $cut_list_aref, writing the output to $cut_file

ad_split($src_file, $cut_file, $cut_list_aref)

Split the $src_file at the points specified in the ARRAY ref $cut_list_aref, writing the output files to $cut_file with suffix XXXX where XXXX is in incrementing count starting at 0001

ok_to_detect($settings_href)

Looks at the settings and returns TRUE if the settings are such that advert detection will be preformed (i.e. detection_method is not 'disabled' or 0)

write_default_config( [$force], [$search_path] )

Writes a default Advert config file. If the optional $force parameter is set, then writes a new file even if one already exists. Uses the optional search path to find a writeable directory (other than the default search path).

ACKNOWLEDGEMENTS

libmpeg2

This module uses libmpeg2 for MPEG2 video decoding:

* Copyright (C) 2000-2003 Michel Lespinasse <walken@zoy.org>
* Copyright (C) 1999-2000 Aaron Holtzman <aholtzma@ess.engr.uvic.ca>
*
* See http://libmpeg2.sourceforge.net/ for updates.
*
* libmpeg2 is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* libmpeg2 is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

mpegaudiodec

This module uses mpegaudiodec for AAC audio decoding:

* MPEG Audio decoder
* Copyright (c) 2001, 2002 Fabrice Bellard.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Comskip

Copyright (C) 2004 Scott Michael

Thanks to Erik Kaashoek for answering a few of my inane questions, and thanks to Comskip for providing the inspiration for the detection algorithms.

AUTHOR

Steve Price

Please report bugs using http://rt.cpan.org.

BUGS

One "problem" is when trying to run this code under Cygwin. With large videos, the combination of Perl's excessive memory allocation and cygwin's draconian heap size allocation results in running out of memory. This can be alleviated by increasing cygwin's heap size, but a re-write of my code to use XS for all the large data structures would fix it (but make the analysis section more dependent on calling XS, rather than being pure Perl)

FUTURE

Subsequent releases will include:

  • Re-write of analysis section to make it use simpler, generic routines so that it is easier for me (and you) to glue sequences of operations together

  • Re-write to provide XS memory handling routines

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Steve Price

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.