lakestonelabs/comgone repository overview

⁠ComGone

ComGone will analyze a video episode file (using Comskip) and remove the commercials. Code repository can be found here: https://codeberg.org/lakestonelabs/comgone⁠

⁠Prerequisites

• A Linux system or WSL
• Docker
  • Prebuilt containers can be found here: https://hub.docker.com/r/lakestonelabs/comgone⁠
• Matching username IDs. If your host username that owns the show files is not UID/GID of 1000 it's recommended to rebuild the container with the proper UID/GID values. See the building section for details. Use id -u and id -g on your host to get these values.

⁠Features

• First-class support for MKV/mp4/m4v file containers
• Uses ffmpeg's "input seeking" for faster processing
• Relies on Comskip for actual commercial detection (baked into container image)
• Includes a good version of Comskip's ~/.comskip.ini file
• Batch, single-file, or daemon mode
• Date filter (batch mode)
• First-class support for Jellyfin post-processing of recorded DVR shows
• Parallel processing via threads for improved performance
• Asynchronous code execution for enhanced responsiveness and easier-to-read code

⁠Usage

ComGone can be ran in daemon mode for post-processing, or on-demand via the docker run command. Prebuilt container images can be found here: https://hub.docker.com/r/lakestonelabs/comgone⁠

⁠Environment Variables

⁠Daemon mode

Daemon mode is to be used for on-demand sending of dynamically-created videos for commercial processing. This would be "post-processing" for Jellyfin's DVR functionality. So when Jellyfin is finished recording a DVR show it will then send said recording to ComGone.

The<full_root_path_to_vides> volume must be exposed to the container. The path exposed to the container (right side of the colon) MUST MATCH that of the path used in your other program (Jellyfin, etc.) that's generating the videos. For example, if you're running Jellyfin in a docker container, the Jellyfin's internal path for where the DVR shows are being written to must be used for GomGone's container volume.

Sending video files to ComGone can be accomplished in two ways:

1. By using the jellyfin-post-processing.sh script. Use this script as the "post-processing" option in Jellyfin's DVR section. See the script's usage documentation.
2. Manually sending the file info via your own script.
   1. Socket - By sending the full path of the show to the daemon unix socket file (usually created at /tmp/comgone/comgone.sock). It's assumed that in this mode you'll be sending files to be processed via the unix socket that ComGone creates for Inter Process Communication. Therefore, the /tmp/comgone directory must be exposed to both the ComGone and Jellyfin,etc. containers.
   2. Network - By sending the full path of the show to the Comgone's network address on port 4746 .

⁠Docker run - socket method

• Create the /tmp/comgone directory on your host's filesystem.
• Expose the above directory to your DVR docker container, i.e. Jellyfin, etc. (-v /tmp/comgone:/tmp/comgone)

    docker run -it -e DAEMON_MODE=socket -v /tmp/comgone:/tmp/comgone --user 1000:1000 -v /<full_root_path_to_vides>:/episodes lakestonelabs/comgone:0.7.3.2

⁠Docker run - network method

    docker run -it  -e DAEMON_MODE=network -p 4746:4746 --user 1000:1000 -v /<full_root_path_to_vides>:/episodes lakestonelabs/comgone:0.7.3.2

⁠Docker compose method

The latest docker-compose.yml file can be found in the Codeberg repository.

services:
  comgone:
    image: lakestonelabs/comgone:0.7.3.2
    container_name: comgone
    restart: unless-stopped
    user: 1000:1000
    environment:
      - DAEMON_MODE=<mode>  # Modes: socket|network
      - KEEP_EDL=false
      - MAX_WORKERS=2
      - OVERWRITE_ORIGINAL=true
    volumes:
      - <dir_to_episodes>:/episodes
    ports:
      - 4746:4746

⁠Jellyfin post processing for Daemon mode

When in Daemonm mode, ComGone will listen on port 4746 (or via a socket). Use the included post processing script from the git repo, or use any other script/program that can write to a raw TCP network endpoint.

It is recommended to configure your Jellyfin container with its own internal network. If you've already done so, proceed to the next step.

Use the below as an example to configure a dedicated docker network for your container in the docker-compose.yml file.

networks:
  jellyfin:
    driver: bridge

services:
  jellyfin:
    container_name: jellyfin
    volumes: 
      - <host_path_to_drv_recordings>:/videos/tv/live/recordings
      - <host_path_to_jellyfin_scripts>:/jellyfin-scripts
    networks:
      jellyfin:

  comgone:
    container_name: comgone
    volumes: 
      - <host_path_to_drv_recordings>:/videos/tv/live/recordings
    networks:
      jellyfin:

• Copy the jellyfin-post-processing.sh file from the git repo to a location on your host that is mounted into your Jellyfin container.
  • Make sure this script is executable. For example, run: chmod +x <path_to>_jellyfin-post-processing.sh
• Inside your Jellyfin UI go to Dashboard->DVR->Recording Post Processing
• In the Post-processing application field specify the Jellyfin's container internal path the above jellyfin-post-processing.sh file.
  • Example, use: /jellyfin-scripts/jellyfin-post-processing.sh
• For the Post-processing command line arguments field specify: comgone:4746 "{path}". If your container's network name is different then replace comgone with the correct container name.
  • NOTE: If you're using a different method to resolve/access the comgone container then use it instead in the comgone in comgone:4746.

⁠Single-file mode

Simply supply the path to the video file you want to process at the end of the docker run command. Specify options prior to the path.

docker run -it --user 1000:1000 -e OVERWRITE_ORIGINAL=true -v /<dir_to_episodes>:/episodes lakestonelabs/comgone:0.7.3.2 '/episodes/Game of Thrones S01E01.mkv'

⁠Batch mode

Batch mode will search for video files to process based on the path passed at the end of the docker run command. Specify options prior to the path.

docker run -it --user 1000:1000 -e OVERWRITE_ORIGINAL=true -e RECURSIVE=true -e MAX_WORKERS=2 -v <dir_to_episodes>:/episodes lakestonelabs/comgone:0.7.3.2 /episodes

⁠Batch mode with date filter

The below docker command will only process files that match the --date_filter criteria. Supported filter operators are: >, >=, <, <=, ==, !==

docker run -it --user 1000:1000 -e OVERWRITE_ORIGINAL=true -e RECURSIVE=true -e MAX_WORKERS=2 -v <dir_to_episodes>:/episodes lakestonelabs/comgone:0.7.3.2 --date_filter=">= 2025-02-24" /episodes

NOTE: To kill/stop a running instance you'll need to issue Ctrl-C twice. This is because each file that is processed is given its own worker thread.

⁠Tuning

You can tune various parts of comskip program that is responsible for the actual commercial detection. To do this you can copy the .comskip.ini file, which is baked into the container, onto your host system and change the various settings. Some of the comskip settings are related to commercial detection and some are for performance tuning.

• Performance tuning
  • You can adjust the thread_count .comskip.ini setting for faster processing. DO NOT set to more than the max number off CPU threads on your host system.
    • NOTE: If running in "batch" mode then you must take the MAX_THREADS and thread_count into account as to not exhaust your system's CPU resources.
• Other tuning parameters - Most of the other settings in the .comskip.ini file are outside the scope of this project. Please refer to online discussions regarding these settings for more information.

⁠Building

• Git clone this project:
  • git clone https://codeberg.org/lakestonelabs/comgone.git
• Change directory to the cloned location.
• Run docker build -t lakestonelabs/comgone:<version_tag> .

⁠FAQs

⁠Why not just use ComChap?

• Comchap does not have support for mkv container files.
• It uses ffmpeg's "output seeking" option which has poor performance when splicing files.
• Is written as a bash script. While this is completely fine, for me, it's hard to read and debug.
• Is not under active development. As of this writing the last push for the bash script was seven (7) years ago.

⁠Why do I see log errors "... corrupted double-linked list"?

This is the underlying Comskip program aborting due to video errors. These are usually caused by a video file being recorded from a bad OTA (Over The Air) signal. If you view the original video file you'll probabaly see a bunch of digital corruption/distortion/pixelation due to poor signal quality. There is nothing Comskip nor ComGon can do about this. It's recommended to check your OTA connections/antenna orientation.

⁠Socials

• @[email protected]⁠ Mastodon⁠