Immersion pod

AJATT-style passive listening and condensed audio without bloat.

Passive immersion is one of the key activities in AJATT. This program lets mpd users convert foreign language movies and TV shows to audio and use it for passive listening. impd supports condensed audio and creates it by default if it finds subtitles in the container or externally.

Installation

Arch Linux and pacman-based distros

Arch Linux users can install the impd-git AUR package and skip to Configuration.

Debian-based distros

Ubuntu and Debian users can install the provided .deb package.

wget https://github.com/Ajatt-Tools/impd/releases/latest/download/immersionpod.deb && sudo dpkg -i immersionpod.deb

Other distros

If you want to package impd for your distro and know how to do it, please create a pull request.

<details> <summary>Manual installation</summary>

1. Install dependencies

   • Mandatory:

     • mpd
     • FFmpeg

   • Optional:

     • mpc - Interaction with mpd.
     • libnotify - Desktop notifications.
     • youtube-dl - Adding audio from Youtube.

2. Clone the repo

   $ git clone 'https://github.com/Ajatt-Tools/impd.git'
   

3. cd into the folder and run make install.

   $ cd impd && sudo make install
   

Alternative to steps 2 and 3:

sudo curl -Lo /usr/local/bin/impd https://github.com/Ajatt-Tools/impd/raw/refs/heads/main/impd
sudo chmod 755 /usr/local/bin/impd

</details>

Configuration

To configure the program create a config file at ~/.config/immersionpod/config.

Available options:

• langs. A comma-separated list of languages, in the order of preference. impd will try to extract audio and use subtitles in the specified language. If the required language is not found, it will try the next preference. If you don't know the code for your language, run impd probe on a desired video file.
• prefer_internal_subs. If set to yes, try to use internal subtitles when creating condensed audio. If impd fails to do so, it tries external subtitles. If the option is set to no, impd tries external subtitles first.
• max_chunk_len_seconds. Skip subtitle lines longer than this number of seconds. 30 seconds by default.
• video_dir. The default directory where your video files are stored. The directory is searched for recently added files when you call impd rotate.
• bitrate. Audio bitrate. It is recommended to keep it rather low to save disk space because impd deals with speech, not music. Speech doesn't require high bitrates.
• recent_threshold. A file is considered recent if it has been modified in the last X days. Audio files that are no longer recent get archived if you call impd archive, and videos get skipped if you call impd add_recent.
• padding. Set a pad to the dialog timings. For example, 0.5 = half a second.
• music_dir. Custom music directory. Set it only when impd fails to automatically detect your music directory.
• line_skip_pattern. Skip subtitle lines matching this RegExp. If empty, no lines will be skipped. Can be used to skip openings and endings by matching lines like ♪〜.
• filename_skip_pattern. Perl RegExp to match the filename of the input file. If it matches, impd skips the file. By default, it is set to skip filenames that contain NCOP or NCED.
• extract_audio_add_args. Defines an array of additional arguments which should be passed to ffmpeg when extracting audio tracks from videos.
• ignored_chapters_pattern. Awk RegExp to match chapters in the input file. If it matches, any subtitle inside the chapter start and end time is ignored. By default, it is set to ignore chapters whose name contains PV, OP, ED, or Intro.

Example config file:

langs=japanese,jpn,jp,ja,english,eng,en,rus,ukr,fre,spa,ger,por,ita,ara,dut
prefer_internal_subs=yes
video_dir=~/Videos/ongoing
bitrate=32k
recent_threshold=10
padding=0.2
line_skip_pattern="^♪〜$|^〜♪$"
filename_skip_pattern="NCOP|NCED"
extract_audio_add_args=(-af loudnorm=I=-16:TP=-1.5:LRA=11)
ignored_chapters_pattern="PV|OP|ED|Intro"

If a value is omitted from the config file, the default value will be used. The config file is sanitized and then sourced.

Usage

Tip: If you store all your immersion material in video_dir like me, the only command you are going to need most of the time is impd rotate.

Add

Convert videos to audio and add them to Immersion pod. impd will guess what audio and subtitles to use:

$ impd add [OPTION] FILE

Options for impd add:

• -r, --recent. Add all files modified in the last recent_threshold days from your video directory to Immersion pod.
• -s, --stdin. Read filenames from stdin.

If FILE is an audio file, it is added as well. You can use this to add existing podcasts or audiobooks to impd.

Add all files more recent than 20 days:

$ impd add --recent --recent-threshold 20
$ impd add -r -t 20

Recents

Print files that will be added if impd rotate is run.

$ impd recents

Adjust number of days to look back.

$ impd recents -t DAYS
$ impd recents -t 20

Condense

Make condensed audio and store it in an arbitrary location:

$ impd condense -i video [-o output audio] [-s subtitle file] [-t subtitle track number] [-a audio track number]

This function gives more precise control than add. If you don't specify output audio, the standard Immersion pod directory will be used. If you specify subtitle file, an external subtitle file will be used. If you specify subtitle track number, an internal subtitle track number will be used. If you specify audio track number, the audio track will be set according to the number instead of being guessed based on the video's metadata.

Note: Run impd probe FILE to output tracks and their corresponding numbers.

Archive

Move episodes older than recent_threshold days to the archive folder:

$ impd archive

Reshuffle

Re-add files to the playlist, shuffle them and start playing:

$ impd reshuffle

Rotate

Archive old immersion material and make new based on videos in your video directory:

$ impd rotate

Equivalent to calling impd add --recent, impd archive and impd reshuffle.

Generate playlist

Create a playlist file named impd.m3u in the immersionpod/current folder.

$ impd mkplaylist

m3u playlists are not needed to immerse by using mpd but they might be necessary when using a different audio player, for example, on an Android device.

Global options

Global options work with any command.

• -f, --force. Overwrite existing files.
• -n, --no-condense. Don't condense audio.
• -t, --recent-threshold NUMBER. Override the recent_threshold config option temporarily.

Examples

Add an arbitrary video to Immersion pod. Condense if possible:

$ impd add -f 'video.mkv'

Add all recently downloaded videos to Immersion pod. Condense if possible:

$ impd add --recent

Use the find utility to search for specific videos. Pipe the output to impd:

$ find /mnt/videos/ | impd add --stdin

Rotate. Archive old episodes and add newly downloaded ones:

$ impd rotate

Tip: Add impd rotate as a cronjob or bind it to any key in your DE, WM, sxhkd, xbindkeysrc, etc.

Condense audio on demand:

$ impd condense -i 'video.mkv' -o 'audio.ogg' -s 'subtitles.srt'

Miscellaneous

Convert file to ass or srt:

$ impd sub_conv file.srt file.ass
$ impd sub_conv file.ass file.srt

Extract audio from video without condensing:

$ impd extract_audio 'video.mkv' audio.ogg

Extract internal subtitles. Format is guessed based on extension:

$ impd extract_subtitles 'video.mkv' subtitles.srt
$ impd extract_subtitles 'video.mkv' subtitles.ass

Extract subtitles from all videos in a folder:

for video in ./*.mkv; do
    impd extract_subtitles "$video" "${video%.*}.ass"
done

Print video, audio and subtitle tracks available in the container:

$ impd probe 'video.mkv'

Add an arbitrary audio to Immersion pod:

$ impd add ~/podcast.mp3
$ impd add 'https://podcasts.com/podcast.mp3'

Download and automatically add podcasts or YouTube videos to Immersion pod.

If you use Newsboat, you can define a macro to add a video or audio to Immersion pod. Install tsp, then open your ~/.config/newsboat/config and add the macro:

browser firefox
macro i set browser "tsp impd add" ; open-in-browser ; set browser firefox -- "Add to Immersion pod"

Next time you open Newsboat, you'll be able to press the macro-prefix (usually ,) followed by i to call impd add.

Print title of a video:

$ impd fetch_title 'video.mkv'

Condensing

For condensing