CNSR vlc viewer add-on

VLC add-on for real-time media censorship according to user personal settings, using CNSR file format.

This add-on censors categories like nudity, verbal abuse, violence and alchohol and drug consumption. The add-on is also available here.

This add-on is inspired by MEDERI's "Time v3.2" vlc extension.

Supported OS: Windows, Linux and Mac OS.

Installing the add-on for regular use

1. If you don't have VLC installed on your computer, install it now from VLC

2. download the repository: press on the "CODE" green button, and choose the option: "Download zip".

3. Using the installation file (currently only available for Mac OS):

   1. Open your terminal, cd into CNSR repo and run python3 scripts/install.py, you'll need to enter your administer's password
   2. A link between the project's files and VLC repository is generated. For example, a file named cnsr_intf.lua that points to cnsr-vlc-viewer-addon/intf/cnsr_intf.lua will be created in /Applications/VLC.app/Contents/MacOS/share/lua/intf. Every change that will be made in cnsr-vlc-viewer-addon will be also made to the installed extension.
   3. You can now jump to instruction #6, and also skip the entire "Setting up the project for development" section.

4. If you want the add-on to be available for all the users of the computer, access the lua folder using these paths:

   • Windows- %ProgramFiles%\VideoLAN\VLC\lua
     or %ProgramFiles (x86)%\VideoLAN\VLC\lua
     
   • Linux- /usr/lib/vlc/lua or use the command find /usr/lib -iname VLSub.luac to find the directory
     
   • MacOS- /Applications/VLC.app/Contents/MacOS/share/lua
     
     If you want the add-on to be available only for a specific user, access the lua folder using these paths:
   • Windows- %APPDATA%\VLC\lua
     
   • Linux- ~/.local/share/vlc/lua
     
   • MacOS- /Users/%your_name%/Library/Application Support/org.videolan.vlc/lua
     If the paths above don't exist and you already have VLC installed on your computer try to uninstall it and then reinstall it. Then, make sure you are using the most updated version of VLC.

5. Extract the contents of the cnsr-vlc-viewer-addon-main directory within the downloaded zip file into the lua folder.

6. Start the Extension in VLC menu

   • View > cnsr for Windows/Linux.
   • VLC > Extensions > cnsr for Mac OS.

7. Choose your password and your password's hint, please choose a password you will remember and your child will not know. Click save to set the cnsr interface script as an extra interface.

8. Restart VLC

9. Start the Extension again in VLC menu

   • View > cnsr for Windows/Linux.
   • VLC > Extensions > cnsr for Mac OS.

10. Configure the cnsr categories to your liking.

How to use CNSR files:

CNSR files are not created automatically, they must be downloaded or created manually
(in the future a tagging tool will be available) by watching the video and writing tags with time-stamps.

Possible tags:

1. for violence
   
2. for verbal abuse
   
3. for nudity
   
4. for alcohol and drug use
   

You can see an example of a cnsr file here

• Explanation of the timestamps displayed: hours:minutes:seconds,millis

In order to make use of cnsr file you need to create a new file with the format as shown in example/example_file.cnsr.
The file name must be identical to the video name you want to play (except for the file type), and must be at the same directory as the video.

For example, if the video you want to play is:
/foo/bar/myvid.mp4
Then the cnsr file should be:
/foo/bar/myvid.cnsr

NOTICE

• Currently there is an issue with directories that have hebrew in their path, so try to avoid them

Setting up the project for development

To work conveniently with git, we recommend cloning the project in your exsisting lua folder.
Since git doesn't allow to clone a project into an existing folder, we reccomend following these steps:

1. If you don't have VLC installed on your computer, install from VLC

2. If you don't have Git installed on your computer, install from Git

3. Open a terminal\CLI with admin privileges:

   • Windows- WinKey + x > a and approve UAC.
   • Linux- ctrl + alt + t, type sudo -i and enter password if necessary.
   • macOS- cmd + space >, type terminal type sudo -i and enter password if necessary.

4. Type cd "<lua path>" (find lua path according to section 3 of "Installing the add-on for regular use").

5. type git init

6. type git remote add origin https://github.com/ophirhan/cnsr-vlc-viewer-addon.git

7. type git fetch origin

8. type git checkout -b main --track origin/main

And that's it! the add-on is installed, and you are ready to start developing.

Tips for developers

• To interact with VLC we use the API documented here.
• For more support you can search this dedicated forum for scripting VLC with lua and specificaly visit this getting started thread.
• When debbuging in order to see the log messages you need to open the VLC messages panel via:
  ctrl + m or command + m
  
• Using a debugger is reported possible and explained here but we haven't tried it.
• Since the lua folder is part of the vlc installation directory and writing to it might be proteced,
  in order to save your changes you might need to open your IDE as an administartor.
  

Getting started with lua

If you're just getting started with lua, here are some important things that set it apart from other programming languages:

• tables are equivalent to hashsets and arrays simultaneously, their index starts from 1 (not 0).
  
• lua is an interperted language no need to build anything!
  
• As for a prefered IDE we use intellij IDEA with emmyLUA plugin, but eclipse should work as well (maybe better).
  

For more on lua this tutorial will help you get up and running in little to no time.

How To Contribute?

If you are not an approved collaborator, changing and pushing to the main branch is not possible, in order to contribute to our code you'll need to:

1. Fork this repo.
2. Work on a new local branch.
3. Push the changes from the local branch to github.
4. Create a new pull request (to merge the changes from you branch to our main branch), and wait for it's approval.

Founders

Eyal Ben Tovim Ophir Han Eldar Lerner