Guardian Package API

This section contains the complete API reference for the Guardian package.

Core Module

Core functionality for the Guardian media censoring system.

class guardian.core.SegmentDiagnostic(segment_id, start_time, end_time, duration, target_rms_db, actual_rms_db, meets_threshold, strategy_used, strategy_name, filter_applied)

Bases: object

Diagnostic information for a single censored segment.

segment_id: int

start_time: float

end_time: float

duration: float

target_rms_db: float

actual_rms_db: float

meets_threshold: bool

strategy_used: int

strategy_name: str

filter_applied: str

__init__(segment_id, start_time, end_time, duration, target_rms_db, actual_rms_db, meets_threshold, strategy_used, strategy_name, filter_applied)

class guardian.core.CensoringDiagnostic(timestamp, input_video, output_video, total_segments, total_censored_duration, successful_segments, failed_segments, final_strategy_used, fallback_attempts, overall_success, segments, error_messages, recommendations)

Bases: object

Complete diagnostic report for a censoring operation.

timestamp: str

input_video: str

output_video: str

total_segments: int

total_censored_duration: float

successful_segments: int

failed_segments: int

final_strategy_used: int

fallback_attempts: int

overall_success: bool

segments: List[SegmentDiagnostic]

error_messages: List[str]

recommendations: List[str]

__init__(timestamp, input_video, output_video, total_segments, total_censored_duration, successful_segments, failed_segments, final_strategy_used, fallback_attempts, overall_success, segments, error_messages, recommendations)

class guardian.core.GuardianProcessor(matching_words=None, ffmpeg_cmd=None, ffprobe_cmd=None)

Bases: object

Main processor class for censoring profane content in video files.

DEFAULT_MATCHING_WORDS = ['fucking', 'fuck', 'shit', 'damn', 'hell', 'ass', 'bitch', 'bastard', 'bullshit', 'fucker', 'fucked', 'asshole', 'piss', 'jesus christ', 'jesus', 'sex', 'pussy', 'son of a bitch', 'sonofabitch', 'jackass', 'smartass', 'tits', 'whore', 'cunt', 'slut', 'boobs', 'orgasm', 'penis', 'blowjob', 'handjob', 'hard on', 'cocksucker', 'dipshit', 'horseshit', 'jack off', 'nympho', 'rape', 'fuckface', 'skank', 'shitspray', 'bitches', 'nigga', 'nigger', 'dickhead', 'prick', 'arsehole', 'motherfucker', 'goddamn', 'shithead', 'douchebag', 'fag', 'faggot']

__init__(matching_words=None, ffmpeg_cmd=None, ffprobe_cmd=None)

Initialize the GuardianProcessor. :type matching_words: Optional[List[str]] :param matching_words: Custom list of words to censor. Uses default if None. :type ffmpeg_cmd: Optional[str] :param ffmpeg_cmd: Path to ffmpeg executable. :param Defaults to checking local ‘bin’ dir.: :type ffprobe_cmd: Optional[str] :param ffprobe_cmd: Path to ffprobe executable. :param Defaults to checking local ‘bin’ dir.:

get_video_details(filename)

Extracts video and audio details using ffprobe.

Parameters:

filename (str) – Path to the video file.

Return type:

Optional[Dict[str, Any]]

Returns:

Dictionary containing video duration, audio codec, sample rate, channels, video width, height, and frame rate.

extract_embedded_srt(video_path, output_srt_path)

Extracts the first embedded SRT subtitle track from a video file, prioritizing default tracks.

Parameters:

• video_path (str) – Path to the input video file.

• output_srt_path (str) – Path where the extracted SRT file will be saved.

Return type:

bool

Returns:

True if an SRT track was successfully extracted, False otherwise.

censor_audio_with_ffmpeg(video_path, output_path=None, full=False)

Censors profane audio segments in a video file using FFmpeg. :type video_path: str :param video_path: Path to the input video file. :type output_path: Optional[str] :param output_path: Optional custom output path. If None, generates :param default name.:

Return type:

Optional[str]

Returns:

Path to the newly created censored video file, or None if an error occurred.

process_video(video_path, output_path=None)

Main method to process a video file and create a censored version.

Parameters:

• video_path (str) – Path to the input video file.

• output_path (Optional[str]) – Optional custom output path.

Return type:

Optional[str]

Returns:

Path to the censored video file, or None if processing failed.

CLI Module

Command-line interface for the Guardian media censoring system.

guardian.cli.setup_logging(log_file=None, verbose=False)

Configure logging for the application.

Parameters:

• log_file (Optional[List[str]]) – Optional path to log file. If None, uses script name.

• verbose (bool) – If True, sets DEBUG level, otherwise INFO.

Return type:

None

guardian.cli.expand_input_paths(input_paths)

Expand input paths to include video files from directories.

If an input path is a directory, discover all video files in that directory. If an input path is a file, include it as-is.

Parameters:

input_paths (List[str]) – List of file or directory paths provided by user.

Return type:

List[str]

Returns:

List of file paths to process.

guardian.cli.create_parser()

Create and configure the argument parser.

Return type:

ArgumentParser

guardian.cli.validate_args(args)

Validate command line arguments.

Parameters:

args (Namespace) – Parsed command line arguments.

Return type:

bool

Returns:

True if arguments are valid, False otherwise.

guardian.cli.main()

Main entry point for the CLI application.

Return type:

int

Returns:

Exit code (0 for success, 1 for error).

Package Module

Dialogue Guardian: Universal Media Censor

A Python package for automatically detecting and censoring profane language in video files by processing SRT subtitle files.

class guardian.GuardianProcessor(matching_words=None, ffmpeg_cmd=None, ffprobe_cmd=None)

Bases: object

Main processor class for censoring profane content in video files.

DEFAULT_MATCHING_WORDS = ['fucking', 'fuck', 'shit', 'damn', 'hell', 'ass', 'bitch', 'bastard', 'bullshit', 'fucker', 'fucked', 'asshole', 'piss', 'jesus christ', 'jesus', 'sex', 'pussy', 'son of a bitch', 'sonofabitch', 'jackass', 'smartass', 'tits', 'whore', 'cunt', 'slut', 'boobs', 'orgasm', 'penis', 'blowjob', 'handjob', 'hard on', 'cocksucker', 'dipshit', 'horseshit', 'jack off', 'nympho', 'rape', 'fuckface', 'skank', 'shitspray', 'bitches', 'nigga', 'nigger', 'dickhead', 'prick', 'arsehole', 'motherfucker', 'goddamn', 'shithead', 'douchebag', 'fag', 'faggot']

__init__(matching_words=None, ffmpeg_cmd=None, ffprobe_cmd=None)

Initialize the GuardianProcessor. :type matching_words: Optional[List[str]] :param matching_words: Custom list of words to censor. Uses default if None. :type ffmpeg_cmd: Optional[str] :param ffmpeg_cmd: Path to ffmpeg executable. :param Defaults to checking local ‘bin’ dir.: :type ffprobe_cmd: Optional[str] :param ffprobe_cmd: Path to ffprobe executable. :param Defaults to checking local ‘bin’ dir.:

get_video_details(filename)

Extracts video and audio details using ffprobe.

Parameters:

filename (str) – Path to the video file.

Return type:

Optional[Dict[str, Any]]

Returns:

Dictionary containing video duration, audio codec, sample rate, channels, video width, height, and frame rate.

extract_embedded_srt(video_path, output_srt_path)

Extracts the first embedded SRT subtitle track from a video file, prioritizing default tracks.

Parameters:

• video_path (str) – Path to the input video file.

• output_srt_path (str) – Path where the extracted SRT file will be saved.

Return type:

bool

Returns:

True if an SRT track was successfully extracted, False otherwise.

censor_audio_with_ffmpeg(video_path, output_path=None, full=False)

Censors profane audio segments in a video file using FFmpeg. :type video_path: str :param video_path: Path to the input video file. :type output_path: Optional[str] :param output_path: Optional custom output path. If None, generates :param default name.:

Return type:

Optional[str]

Returns:

Path to the newly created censored video file, or None if an error occurred.

process_video(video_path, output_path=None)

Main method to process a video file and create a censored version.

Parameters:

• video_path (str) – Path to the input video file.

• output_path (Optional[str]) – Optional custom output path.

Return type:

Optional[str]

Returns:

Path to the censored video file, or None if processing failed.

guardian.main()

Main entry point for the CLI application.

Return type:

int

Returns:

Exit code (0 for success, 1 for error).