MOVIE CLEANUP

For years I used the TVGuardian device to filter profanity from my movies, but it did not have the ability to handle all DVDs and Blu-ray movies due to the lack of closed captioning.  Like many others I too looked for a free solution and stumbled upon the "Mute Profanity" plugin from Scott Brown, used in Kodi Media Player (formally XBMC).  This is my attempt to share knowledge and processes to make the default Kodi player mute, skip and superimpose a solid black screen when applicable.  Using these three options it is possible to mute audio (profanity), skip video (inappropriate scenes) and cover video while retaining audio by using subtitles vector shapes (cover inappropriate scenes while still listening to the story line).  The use of the Mute Profanity plugin makes automating a lot of this possible by creating Edit Decision List (edl) file to control the mute and skip functions for each movie. The web page instructions are from a Windows 10 client, but the resultant files can be used with the movie on any supported Kodi system.
Download my edl files available for your use.

Note: The edl skip functionality is broken in the current version of Kodi (version 18.x).  I have successfully tested this functionality in version 16.x.  Further development of version 18.x should address the issue.

Mute Profanity - Kodi Forum
Mute Profanity - Github
Mute Profanity plugin download (zip file). Install through Kodi system plugin menu

Use the following link to configure Kodi with the plugin (this is where I started).  Great guide for setting up Kodi and the plugin.
Zeilk Creative - Remove Profanity From Movies The Easy Way!
PDF of above link.

Table of contents:

• EDL - how it works in Kodi - simplified
• Mute Profanity plugin - Muting
• Skip entries
  
• Verifying the contents of the edl
  
• Edited For Content - Superimposing\covering the video
• Process Outline (my briefly ordered steps)
• Troubleshooting
• My files
• Edit Decision List (edl) Files
• PowerShell Scripts
• Other Files
  

EDL - how it works in Kodi - simplified)

Kodi uses a Edit Decision List (EDL).  Basically it is a text file that is named the same as the movie with an extension of .edl. The following notation is used:

[start time] [end time] [action]

Start and end times can be in:
Seconds:

95.728
00095.7
00095.728

4276.6
04276.600

Or timecode:
00:01:35.728

Note: Do not use a comma or alternate character for the period before the last three zeros in a timecode entry. - 00:00:00.000
Note: Do not mix seconds and timecode entries on the same line:
            04276.600  01:59:35.728  1  #THESE TIME STAMPS ARE MIXING NOTATIONS AND ARE INVALID TOGETHER

Actions may be "0" for skip or "1" for mute. The action will be performed between the two time-frames

The sequence of each time-frame and action do not have to be in ascending order (it just makes it easier to read).  In fact I like to keep all my video skips at the end of my file in timecode format.

Note: Mute and Skip time-frames can not overlap otherwise no action will occur

Comments at the beginning of a line can be included with a hash symbol (pound symbol #) and a space before the comment text
Comments after the action simply use a hash symbol and then the text

Examples:

# EDITS
00:00:00.042    00:00:34.456    0    #SKIPPING INTRO
01:04:23.849    01:05:12.054    0    #sex scene
# REV_1

Using the edl file

In short, you could watch your movie and then use accurate time stamps to mute and skip content.  Name the file exactly the same as your movie file but with the .edl extension and keep the file in the same location as the movie file.

Mute Profanity plugin

The Mute Profanity plugin compares a filter.txt file (%AppData%\Kodi\addons\mute-profanity-master\resources\filter.txt) that contains profanity words with the subtitle file.  Based on the timestamps in the subtitle file, it calculates where the filtered word probably is.

The plugin is not used for the playback of a movie but is used for automating the creation of the edl file that controls what the player does (skip\mute).  I use the plug in on my computer where I edit the movie but not on my Android media player where I watch the edited movies that is hooked to my TV.

Subtitle issues

It is my experience that the results from the  Mute Profanity plugin can be between 30%-99% accurate.  Why the big difference?  Its really not the plugins fault, but is wholly dependent upon the subtitle file that is used.  Since the subtitle file is downloaded from opensubtitles.org , it is dependent upon the work of other individuals.  Issues can arise from any of the following:

• Movies from different media (VHS; DVD; Blu-ray; web) have time different run times. Additional company logos etc.
• Movies from different regions (different countries) are encoded at different frames per second, which affects the subtitles time (23.97 fps VS 25.00 fps).  The subtitles may be synchronized at the beginning of the movie but not in the middle or the end.
  
• Movie versions\variants (extended versions; collector editions) have different run times and content.
  
• Subtitle time stamps are incorrect
• Subtitle text is incorrect - For example OCR may use double numeral ones instead of two letter "L"s as in "he11" VS "hell
• Profanity that is not displayed in the subtitles
  

Known Mute Profanity issues:

• Words in the subtitles ending with an apostrophe (single quote) will concatenate the filtered word and the following word together.  If you find these, simply search for the offending word in the subtitle file; remove the apostrophe and re-run the plugin for this movie.
  Example:
  "watch the freakin' car" - resultant filtered word is "freakincar" rather than just the word "freakin"
  

Mute Profanity configuration adjustment

If you have not configured Kodi nor the plugin, please use Zeilk Creative - Remove Profanity From Movies The Easy Way! tutorial.

In the plugin settings, unselect the configuration option "Replace found profanity with **** in subtitle file".  This is necessary to keep the profanity in the subtitle file for reuse by other tools or re-running the plugin after making adjustments.

Using the Mute Profanity plugin

For your movie to show up in the Mute Profanity movie list, it must have gone through the scraping process so that it retrieves the correct movie database information.  After selecting your movie to be processed, the plugin first looks for an existing subtitle file with the same as the movie before attempting to download one.

• If a subtitle file can not be found, the plugin will throw an error (retry several times) and you will need to download or create a subtitle file from an alternate source and re-run the plugin.  I have successfully used the following sites to download subtitles (must be in the .srt format and not .sub):
  www.opensubtitles.org
  www.subsmax.com
  

• To extract subtitles from DVD or Blu-ray media, I have successfully used the following tools:
  https://www.ccextractor.org - Extracts Closed Captions (CC) from DVDs if present
  How do I convert DVD to srt subtitles - Instructions to extract subtitles from DVD
  How to extract subtitles from a Blu-ray and convert to srt - Instructions to extract subtitles from Blu-ray
  

• If you don't have a DVD or Blu-ray source, you can choose to skip using the plugin and manually create your own edl file by watching the movie and creating entries for each profanity. See the "how it works in kodi" section

When the plugin has completed its process successfully, you will find a subtitle (.srt) and a edit decision list (.edl) file with the same name as the movie, in the same location as the movie.  If the downloaded subtitle file is accurate the edl file will be good.  Verify that the subtitles file is accurate by playing the movie in your favorite player that can display subtitles.  Verify the following:

• Do the subtitles continue to match at the beginning and ending of the movie with the same offset (if any)?  If the subtitles were created from a source from another region of the world, the frames per second (fps) may be different and cause your subtitles to be out of sync.
• Do the subtitles appear mostly when a person begins to speak the words or do they appear before or after?  It is best if the subtitles appear at the exact moment the actor speaks.  If the subtitles need to be shifted:
  
• Download the free Aegisub program and install it.
• Load the subtitle file.
  
• From the "Timing" menu select "Shift times".  Use the interface to shift the subtitles forward or backwards.
• Save the changes to the .srt file.  If you are prompted to save as an .ass file, press cancel.  You will need to use the "File|Export Subtitles" option to save the changes as a .srt file (overwrite the downloaded subtitle file).
• Test your movie file to verify the results.  Continue shifting until the subtitles appear at the moment the words are spoken.
  
• Run the Mute Profanity plugin again and it will use your modified subtitles file when processing.
  

This completes the use of the Mute Profanity plugin portion

Verify the contents of the edl

Remove mute false positives

Open the edl file in a text editor and look for any false positive entries.  These may be correct uses of god, hell, balls etc.  Since the plugin only identifies the word that was blocked, it can be difficult to know the context without searching the subtitle file for each occurrence.  I created a PowerShell script (_ProfanityContext.ps1) that will use the same filter.txt file as the plugin.  It will search and create a report for each line where the word was found.  You can find the script in the PowerShell Scripts section.  The following is an example of the script's output:

Add any skip entries

If you are aware of any scenes in the movie that you want to skip, you will need to find them and manually add this information.  See below.

Configure HPC-HC and its usage

For exact timestamps, I use the free HPC-HC video player.  You can customize the hot keys to display the time stamps that can be copy\pasted to the edl file.  The "Go To" function can configured by using the "View" Menu, "Options" item.  Under "Player|Keys" option, configure the "Key" combination you want to use to bring up the timestamp.

If the "Go To" hot key is set to Ctrl+G, I would perform the following:

1. Play the movie in the HPC-HC player.
2. Find the exact spot where the skip\mute should begin.
1. The arrow keys can be used for small increments
2. Ctrl+arrow key will advance one frame at a time
3. Skip only: For the beginning of the skip, reverse three frames
1. It has been my experience that the Kodi player dips about three frames into the skip environment with a brief pause (dependent upon the hardware capabilities).  It can be very embarrassing if the pause is a still frame of an undesired image that you are trying to skip.
4. Read the timecode from the bottom status bar or use the following key sequences to put the same timecode on the clipboard (to paste into the edl).
1. CTRL + G --This displays the Go To menu
2. CTRL + A --This select all the text in the field where the cursor is blinking (selects all the timecode)
3. CTRL + C --This copies the selected text to the windows clipboard (system memory)
4. Open the edl file; place the cursor on an empty line (bottom of the file is good); right click and paste (CTRL + V)
5. If you want to use seconds (default for the plugin) instead of the timecode, use my "_TimeCodeConverter.ps1" PowerShell script
   
6. Press the "Tab" key to separate the next function.
   
5. Find where the skip\mute should end.  Skip only: Add an additional two frames. 
   
6. Repeat step four
1. Press the "Tab" key and type a number zero for skip or a number one for mute.
2. Press the "Tab" key and type a "#" followed by any text comment you want to make.  For example:
   
   

   00:21:15.983    00:22:38.732    0    #Sex scene

7. Save the changes to the edl file and test that the skip\mute performs as expected.
8. Note: Any overlapping mutes and skips will invalidate both functions.  Make sure you comment out any conflicting mutes.

Verify each mute

This process took me the longest and is the most time consuming, but also the most important.

• You could watch the movie and write down each missed or incomplete profanity.  In fact this is the only way to catch profanity that is not documented in the subtitles file.  I used a printed form to keep track of the movie\timeframe\profanity for later cleanup.  You can find the blank template in the Other files section.
• You'll need a tool to convert the timeframe between seconds (that the plugin uses) and timecode (human readable).  I wrote a PowerShell script (_TimeCodeConverter.ps1) to accept seconds and convert it into a timecode (and vice versa).  You can find it in the PowerShell Scripts section.
• I wanted to be more proactive and wrote a PowerShell script (_EdlCurseJumperCreator.ps1) that would skip from the beginning to the first mute and then skip to the second and so on in order to see if the mute was accurate.  This has drastically sped up my validation times.You can find the script in the PowerShell Scripts section.

Edited For Content - Superimposing \ covering the video

Sometimes it is necessary to simply cover the screen if you do not want to skip the scene (plot dependent) and hear the audio.

• Download the free Aegisub program and install it.
• Open my template file (EditedForContent_Subtitle_Template.ass) from the Other Files section
• This file has a dual entry for the beginning of the movie (visual verification that the ass file is working)
• There is also a dual entry that configures a black box to fill 99% of the screen
• Use the "Video" menu item and select "Open Video"
• Browse and select your movie file and wait for it to load.
  
• You may ignore the resolution mismatch if your video is smaller than 1920x1080
  
  
  
  
• The program GUI will change to display a video window.
• Modify the last dual entries (last two entries)
• The line with the text "*Edited For Content*" adds the desired text on the screen.  Select this line to make changes in the video and top working areas
  
• If you want to word wrap your sentence add "\N" where you want it to break.
• The line with the text "*m 1880 1040 l 0 1040 l 0 0 l 1880 0", draws the black box.  Select this line to make changes in the video area.
• There is no need to change the numbers (dimensions)  to make it smaller.
• Use the  red square button on the vertical menu-bar to resize the black box in the video window
  
• Use the four directional button on the vertical menu-bar to drag the square to the desired location in the video window
  
  
  
  
• Save your work as an .ass file with the same name as your movie file
• Play the movie in Kodi and verify your entries
  

Note: Keep only your ass files with your movie file.  You will want to store your srt files in another location away from the movie file or else they will automatically display when an ass file is not present.
Note: Anyone made aware of how this works can easily disable subtitles to avoid the censorship.

Troubleshooting

• The movie does not mute or skip when expected
• Verify that the timestamps are using the same notation (either seconds or timecode, not both)
• Verify that if a time code is used, that the colons and period are in the correct spots (no commas)
• Verify that two entries do not overlap each other.  This can be two mutes; two skips or a mute and a skip
• Verify that you have not left out the "action" number after the timeframe
• Verify that there is not a hash symbol at the begining of the line
  
• When the movie starts it skips minutes into the movie
• If you have a comment (# symbol) on the first entry.  Remove the # or the whole line
• The movie skips to a random scene and then skips again ten seconds later
• The edl file in use was generated from the _EdlCurseJumperCreator.ps1 PowerShell script for verifying mute entries. Replace the edl with a copy from the secondary edl file.  If you do not have this file, remove each line that ends in "Jump".
  

My Files

Edit Decision List (edl) Files

Below you will find a link to my edl files.  99% of my files are based on 23.97 fps (NTSC - Region 1\A).  Even if your movie is at the same speed, it is possible that the timestamps may not match up (differences in source and possible dropped frames in the encoding process to but mention a few).  To help with this situation, I have also included the subtitle file (for comparison) and a "MediaInfo" file that you can use to compare against a "MediaInfo" file generated from your movie file.

If you find there is a constant discrepancy between your movie and my edl, you can use a PowerShell script (_EdlOffSetAdjuster.ps1) to shift all of the edl time entries forwards or backwards.  You can find the script in the PowerShell Scripts section.

Download a comma delimited file (.csv) of all of my edl files
Download all the edl files
Browse for a single movie

PowerShell Scripts

All PowerShell scripts were created and tested in Windows 10 (PowerShell v5).  These are available to you at your own risk.  I will take no responsibility for lost data. Be diligent and backup your edl files before using any of these.

_EdlCurseJumperCreator.ps1
_EdlOffSetAdjuster.ps1
_ProfanityContext.ps1
_TimeCodeConverter.ps1

_EdlCurseJumperCreator.ps1

• Generates a temporary .edl file (0_EdlCurseTestJumper.edl) that:
  
• Calculates a skip from the beginning of the movie to five seconds prior to the first mute.
• Calculates a skip from five seconds past the mute to the next mute (five seconds prior)
• You will be able to hear all the dialog five seconds before and after the mute to verify if it is accurate.
• In cases where there are multiple mutes within the ten seconds, the script will only skip when there is a gap of five seconds or more without a mute.
  

Note: The script strictly looks for entries between the beginning and ending comments for Mute Profanity and assumes all entries are sequential.

Usage:

• Place the script in the same folder as the movie edl
  
• Right-click the .ps1 script and select "Run with PowerShell"
• An enumerated list of all .edl files in the same folder will be displayed
• Select the number associated with the edl file you want to use
• A temporary file will be created (0_EdlCurseTestJumper.edl)
• Make a backup copy of your movie edl file.  DO NOT SKIP THIS STEP
  For example:
  
• If your edl file name is Ghostbusters.edl
• Copy your Ghostbusters.edl file and call it something like GhostbustersBackup.edl
• Now save the "0_EdlCurseTestJumper.edl" as "Ghostbusters.edl" in order to overwrite the original.  We need to make the test file play with the movie.  We will replace the settings using the backup copy when we are done.
• Play the movie in Kodi and it should skip to five seconds prior to the first mute.
• If the mute is acceptable, continue watching as it will skip in five seconds to the next mute
• If you want to make changes to the mute, get an accurate timeframe (see the HPC-HC video player section) and replace entries in both the edl. and backup copy of the edl. It is very important that you update both files as the backup will later replace the active edl.
• If you need to, use the _TimeCodeConverter.ps1 script to convert the timeframe notation to seconds.  This will help you identify which line to edit.
  
• After making timeframe changes remove the text between the second timestamp on the first jump line (timestamp after the 0.042 entry ) and the second time stamp of the jump line above the edit you made. For example
• In the image below, the timestamps were changed on the line with the red box
• Delete the text highlighted in blue
  
  
  
  
• Doing this will have Kodi skip straight to the edit (five seconds prior) you just made so that you can check your work.
  
• Save your changes and start the movie in Kodi (use the "Start from beginning" selection if prompted)
• If you like the changes, keep watching as the movie will skip to the next mute in five seconds.
• After verifying all of your mutes, replace the movie edl file with the backup edl file you created earlier.
• Play the movie in Kodi again to verify that it plays from the beginning and.does not skip around.

Download

_EdlOffSetAdjuster.ps1

Description:
This PowerShell script purpose is to shift the timestamp values in a edl forward or backwards.. 
For example, you have a edl file based off of a movie from a DVD source and now you have the same movie from a Blu-ray source.  When you watch the movie you notice that the mutes and skips are off by about one second. Rather than editing every entry in the file, use this script to shift the timestamps forward or backwards based on a value in seconds.

Usage:

• Determine the amount of seconds the timestamps should be shifted forwards (positive value) or backwards (negative value)
• If you have access to both movie files, find a scene change at the beginning of the movie and calculate the time difference
• If you do not have access to both movie files
• If a MediaInfo file is available from the source media you do not have, run MediaInfo on your movie file and compare duration lengths and or chapter timestamps to make your calculations
• Use a stopwatch (not a very good option, I know...) to calculate the difference.
  
• Place the script in the same folder as the movie edl
  
• Right-click the .ps1 script and select "Run with PowerShell"
• Input your offset value that you calculated - Use a positive number to shift forward (2.25) and a negative number to shift backwards (-0.5)
• Choose the number next to the name of your movie edl file in order to generate a temporary file (0_EdlOffSet.edl) with your new settings.
• Make a backup of your movie edl file and rename the temporary file to the movie edl name.
• Test to see if most mutes are accurate enough or if the timestamps should be shifted again
  

Note: The script will handle either notations in seconds and timecode (00:01:34.843) formats

Download

_ProfanityContext.ps1

Description:
I created this script because the Mute Profanity plugin gives me the filtered word in the comment section of the edl, but not the context of the the sentence where the word was found.  This script will use the same filter.txt file as the plugin; search and create a text file report for each line where the word was found in the subtitles file (.srt).  The following is an example of the script's output:

Usage:

• This process will need to be performed on a computer that has Kodi installed or a copy of the filter.txt file that Kodi uses
• If you use a copy of the filter.txt file and place it outside of the default path, be sure to edit the script (text editor) and change the "$MuteProfanityFile" variable value to the new path where you have stored the file
• Place the script in the same folder as the subtitle file (.srt)
• Right-click the .ps1 script that is saved to your computer and select "Run with PowerShell"
• Enter the number next to the name of the movie subtitle file
• The script will generate a new text file with the same name as the subtitle file and append "_ProfanityContext.txt" to the end of the file
• Numbers in the report correspond to the line number in the subtitle file, should you need to further reference the context
  

Download

_TimeCodeConverter.ps1

Description:

This script will toggle between timeframe notations of seconds (that Mute Profanity plugin uses) and timecode (that humans use - 00:32:35.943).  The output will automatically be placed on the clipboard (in memory) so that it can be pasted into any application.

Usage:

• Right-click the .ps1 script file that is saved to your computer and select "Run with PowerShell"
• When prompted, input time in seconds or timecode notation (00:32:35.943)
• You can also paste a value that you have copied (right-click the console or use the Ctrl + V keys)
  
• The opposite time notation will be output to the clipboard for pasting
• Pressing enter will toggle between the two notations, placing the output on the clipboard each time
  

Download

Other files

Mute Profanity Filter.txt - Copy of the Mute Profanity plugin file that I use (added entries).  Since I have all my Mute Profanity "blocking severity" settings all configured to "Very High" the numbers in the filter.txt are not used (since I block them all).  You may want to adjust the numbers if this is important to you.

EditedForContent_Subtitle_Template.ass - This is a template file for the "Aegisub" application in order to create black boxes to cover the screen.

Documentation form (template) - Print this form and keep it close when watching a movie.  Pause the movie when profanity or a inappropriate scene is experienced that you want to clean up.  Use the form to document the movie; timestamp; reason and come back to edit your movie at a later time.

Last updated  02/25/2019