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

NAME

Linux::DVB::DVBT::Advert::Config - Advert detection config file

SYNOPSIS

	use Linux::DVB::DVBT::Advert::Config ;

DESCRIPTION

This module provides the configuration file utilities for the advert detection and removal utilities.

Settings

Settings are passed into the routines via a HASH ref. Settings also come from the default set, and from any config file parameters. The order of priority for these settings is:

    Default settings LOWEST priority

    Config file (Generic section)

    Config file (Channel-specific section)

    Settings used for detection

    Settings HASH ref HIGHEST priority

Note that the "settings used for detection" only apply if the results from detection are saved in a file, and then this file is read in for analysis (see "Results Files")

Settings are split between those that control the detection phase, and those that control the analysis phase:

Detection Settings

Most of the detection settings (other than detection_method) can safely be left to their default values.

detection_method

Normally leave this set to the default (all methods used). Sometimes you may want to disable all advert detection (for non-commercial channels), or possibly disable logo detection for channels that display a logo at all times.

This variable is actually a bitmap of flags: setting a bit enables the corresponding method. If you know what you want, you can specify the variable as a decimal or hex value. It's recommended, however, to use the following symbols:

disable

Use this symbol on it's own to disable advert detection

default

Use this symbol to specify the built-in default detection method (usually means use all methods)

black

Black frame detection. This is where "black" (or dark) frames are expected to appear before and after advert breaks.

Logo detection. This is where the channel logo is expected to be present during programs, but absent during adverts.

audio

Silence (audio volume) detection. Quiet (or silent) periods are expected before and after adverts.

The symbols above can be combined to specify the complete detection method. Use '+' or '-' before the symbol to enable or disable the method respectively. Using a '+' or '-' before the first symbol specified, results in the symbols being added/subtracted from the default set. Otherwise the set specified are used to fully define the methods to use.

Example: "detection_method = logo + black" means to use only black frame and logo detection.

Example: "detection_method = -logo" means to use default detection methods but disable logo detection.

Example: "detection_method = disable" means to disable advert detection.

frame.schange_jump

Black frame detection: sets the threshold for the step difference of scene score between frames for a scene change to be detected.

frame.schange_cutlevel

Black frame detection: scene change detection percentage above which is deemed a scene change frame

frame.max_black

Black frame detection: maximum pixel value for the pixel to be determined as "black"

frame.max_brightness

Black frame detection: maximum brightness percentage under which is treated as black

frame.brightness_jump

Black frame detection: step difference of the brightness score between frames used to detect a black frame

frame.window_percent

Black frame detection: percentage of frame to use for black frame detection (for example, setting this to 90% results in 5% of the edges around the frame to be ignored)

frame.test_brightness

Black frame detection: pixel value used for brightness detection

frame.noise_level

Black frame detection: noise level used for black frame uniformity detection

logo.logo_edge_step

Logo detection: Step size used for moving between pixels in all logo detection functions. For example, setting this to 2 skips every other pixel, resulting in halving the amount of dtaa to process.

logo.logo_max_percentage_of_screen

Logo detection: Once a logo has been possibly detected, this is a check to ensure that the area of the screen used by the logo is no greater than this value. Otherwise the detected region cannot be a valid logo and is discarded.

logo.logo_window

Logo detection: Number of image frames stored in a rolling detection buffer. The number of frames skipped between each stored frame is set by "logo.logo_skip_frames"

logo.logo_skip_frames

Logo detection: Number of frames to skip between used frames. This creates a bigger discrepancy between images and makes the logo area easier to detect.

logo.logo_edge_threshold

Logo detection: level used to decided whether this is a logo edge

logo.logo_ave_points

Logo detection: The logo detection score is averaged over this number of frames.

logo.logo_checking_period

Logo detection: maximum period (in frames) to use for detecting a logo. If a logo has not been found when we reach this number of frames from the start of the video, then logo detection is cancelled.

logo.window_percent

Logo detection: perecntage of total frame to use for logo detection

logo.logo_num_checks

Logo detection: number of times a logo result is re-checked. Once a logo area is detected, the process is re-started this many times to ensure we don't have a false detection.

logo.logo_ok_percent

Logo detection: the logo detection score % must be above this value before a frame is flagged as containing a logo.

logo.logo_edge_radius

Logo detection: number of pixels to use in logo edge detection

audio.silence_window

Silence detection: adds "fuzziness" to detection of silence frames

Analysis Settings

The analysis settings consist of a global set of settings that are used in all cases. Also, each detection mode (black frame, logo etc) has it's own set of settings that may be set to over-ride the global set. In the same manner as the detection settings, each set if prefixed by it's own namespace (e.g. for black frame detection use 'frame.' etc).

max_advert

The maximum length of a single advert (in frames). Multiple adverts may be joined to form the total advert/commercial break between program sections.

min_advert

The minimum length of a single advert (in frames).

min_program

The minimum length (in frames) of a section of program.

start_pad

(UNUSED) Expected amount of padding (in frames) before the start of a program recording.

end_pad

(UNUSED) Expected amount of padding (in frames) at the start of a program recording.

min_frames

Minimum number of frames to be contracted into a block.

frame_window

fuzziness window when contracting frames into a block

max_gap

widest gap (no valid frames) over which to span when contracting frames into a block

reduce_end

window (in frames) in which to reduce the end of the program to the nearest gap

reduce_min_gap

frame gap used for reducing program end point

Black frame settings (see above to descriptions):

frame.max_advert
frame.min_advert
frame.min_program
frame.start_pad
frame.end_pad
frame.min_frames
frame.frame_window
frame.max_gap
frame.reduce_end
frame.reduce_min_gap
frame.increase_start
frame.increase_min_gap

Logo frame settings (see above to descriptions):

logo.max_advert
logo.min_advert
logo.min_program
logo.start_pad
logo.end_pad
logo.min_frames
logo.frame_window
logo.max_gap
logo.reduce_end
logo.reduce_min_gap
logo.increase_start
logo.increase_min_gap
logo.logo_rise_threshold
logo.logo_fall_threshold

Silence frame settings (see above to descriptions):

audio.max_advert
audio.min_advert
audio.min_program
audio.start_pad
audio.end_pad
audio.min_frames
audio.frame_window
audio.max_gap
audio.reduce_end
audio.reduce_min_gap
audio.increase_start
audio.increase_min_gap

Config File

The configuration file is of the form:

    # global settings
	detection_method = 15
	frame.max_black = 48
	frame.window_percent = 95
	frame.max_brightness = 60
	frame.test_brightness = 40
	frame.brightness_jump = 200
	frame.schange_cutlevel = 85
	frame.schange_jump = 30
	frame.noise_level = 5
	logo.window_percent = 95
	logo.logo_window = 50
	logo.logo_edge_radius = 2
	logo.logo_edge_step = 1
	logo.logo_edge_threshold = 5
	logo.logo_checking_period = 30000
	logo.logo_skip_frames = 25
	logo.logo_num_checks = 5
	logo.logo_ok_percent = 80
	logo.logo_max_percentage_of_screen = 10
	logo.logo_ave_points = 250
	audio.scale = 1
	audio.silence_threshold = -80

	# Channel-specific settings
	[Dave]
	logo.logo_skip_frames = 30
	logo.logo_num_checks = 2
	logo.logo_ok_percent = 85

Config File Search Path

Some of the functions (for example "read_dvb_adv( [$search_path] )") accept an optional search path. If this is specified then the same search path will be used from that point on (until a different search path is specified).

By default, the search path is set to attempt to match with Linux::DVB::DVBT on those platforms that support that path; otherwise the user's home directory is used.

Setting the search path allows the module to attempt to read/write the configuration file from multiple directories. This allows there to be a common global file used by all users, but each user may then create their own configuration file to over ride the global one however they choose.

The format for the search path is an ARRAY ref list of directories, for example:

[ '/etc/dvb', '~/.tv' ]

or

[ 'c:\tv', 'd:\profiles\user\tv' ]

Functions

read_dvb_adv( [$search_path] )

Read the advert settings file and return a HASH ref containing the settings.

Optionally set the search path (see "Config File Search Path")

See "Config File"

write_dvb_adv($href [, $search_path])

Write advert config information

Optionally set the search path (see "Config File Search Path")

write_filename([$search_path])

Returns the advert config file writeable filename path

Optionally set the search path (see "Config File Search Path")

read_filename([$search_path])

Returns the advert config file readable filename path

Optionally set the search path (see "Config File Search Path")

write_default_dvb_adv($href [, $search_path])

Write a default advert config information file

Optionally set the search path (see "Config File Search Path")

read_dir($search_path, $fname)

Find directory to read from - first readable directory in search path

write_dir($search_path, $fname)

Find directory to write to - first writeable directory in search path