Comment lib/copy/* (#LLM-assisted - Claude Code)

configure

@@ -1,25 +1,28 @@
 #!/usr/bin/env bash
 
-# defaults
+# Default install prefix if --prefix= is not provided
 default_prefix=/usr/local
 #default_bindir=$default_prefix/bin
 #default_libdir=$default_prefix/lib
 #default_sharedir=$default_prefix/share
 
+# Parse command-line arguments (only --prefix=VALUE is supported)
 while (( $# ))
 do
 	case "$1" in
-		--prefix=*)	prefix="${1#*=}"
+		--prefix=*)	prefix="${1#*=}"	# Strip the "--prefix=" portion to get the value
 		;;
 	esac
 	shift
 done
 
+# Derive install directories from prefix (or default_prefix if unset)
 bindir="${prefix:-$default_prefix}"/bin
 libdir="${prefix:-$default_prefix}"/lib/AtOM
 sharedir="${prefix:-$default_prefix}"/share/AtOM
 docdir="${prefix:-$default_prefix}"/share/doc/AtOM
 
+# Write Makefile.in so the Makefile can substitute real paths at build time
 cat > Makefile.in <<-EOMakefile.in
 	bindir = "$bindir"
 	libdir = "$libdir"

lib/config/get

@@ -1,27 +1,47 @@
 #!/bin/bash
+
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 getConfig() {
+	# Read the config file line by line; 'key' gets the first word, 'value'
+	# the rest
 	while read key value
 	do
 		case $key in
 			'#'*)
-				#comment
+				#comment - skip comment lines
 			;;
 			'')
-				#empty line
+				#empty line - skip blank lines
 			;;
 			'[general]')
+				# Switch parsing context to the [general] section
 				context=General
 			;;
 			'[source]')
+				# Switch parsing context to the [source] section
 				context=Source
 			;;
 			\[*\])
+				# Any other [section] header is a destination name
 				context=Destination
 				destination="${key#[}"
 				destination="${destination%]}"
-				destinations+=("${destination%]}")
+				destinations+=("${destination%]}")	# Append to list of destinations
 			;;
 			*)
+				# Dispatch key=value to the handler for the current section context
 				getConfig$context
 			;;
 		esac

lib/config/getDestination

@@ -1,30 +1,50 @@
 #!/bin/bash
+
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 getConfigDestination() {
 	case "$key" in
 		'enabled')
+			# 1 = process this destination, 0 = skip it
 			destinationenabled["$destination"]="$value"
 		;;
 		'path')
+			# Strip trailing slash for consistency
 			destinationpath["$destination"]="${value%/}"
 		;;
 		'format')
 			case "$value" in
 				'mp3')
 					destinationformat["$destination"]=mp3
+					# Flag that lame must be present
 					lameneeded=1
-					# MP3 can't handfle more than 2 channels
+					# MP3 can't handle more than 2 channels
 					[[ -z ${destinationchannels["$destination"]} ]]	\
 						&& destinationchannels["$destination"]=2
 				;;
 				'opus')
 					destinationformat["$destination"]=opus
+					# Flag that opusenc must be present
 					opusencneeded=1
 				;;
 				'vorbis')
 					destinationformat["$destination"]=vorbis
+					# Flag that oggenc must be present
 					oggencneeded=1
 				;;
 				'copy')
+					# Files are copied/hardlinked as-is
 					destinationformat["$destination"]=copy
 				;;
 				*)
@@ -34,6 +54,7 @@ getConfigDestination() {
 			esac
 		;;
 		'quality')
+			# Vorbis-only: oggenc quality scale (integer, typically 0-10)
 			expr='^[0-9]*$'
 			if ! [[ $value =~ $expr ]]
 			then
@@ -46,27 +67,32 @@ getConfigDestination() {
 					destinationquality["$destination"]="$value"
 				;;
 				*)
-					echo "Invalid parameter \"$key\" for format \"${destinationformat["$destination"]}\"" >&2
+					echo "Invalid parameter '$key' for" \
+					"format"			    \
+					"'${destinationformat["$destination"]}'" >&2
 					exit $EFMTINVPARM
 				;;
 			esac
 		;;
 		'normalize')
+			# Whether to normalize audio volume (via sox --norm)
 			case $value in
-				'true'|'on'|'yes')
+				'true'|'on'|'yes'|'1')
 					destinationnormalize["$destination"]=1
 				;;
-				'false'|'off'|'no')
+				'false'|'off'|'no'|'0')
 					destinationnormalize["$destination"]=0
 				;;
 				*)
-					echo "normalize takes values:"	\
+					echo "normalize takes values:"	  \
-					"'yes' ,'true' ,'on', 'no', 'false',"\
+					"'yes' ,'true' ,'on', '1', 'no'," \
-					"'off'"
+					"'false','off', '0'"
 				;;
 			esac
 		;;
 		'bitrate')
+			# Opus/MP3: target bitrate in kbps
+			# integer only; Bash doesn't support floats
 			expr='^[0-9]*$'
 			if ! [[ $value =~ $expr ]]
 			then
@@ -88,6 +114,7 @@ getConfigDestination() {
 			esac
 		;;
 		'loss')
+			# Opus Forward Error Correction: expected packet loss percentage (0-100)
 			expr='^[0-9]*$'
 			if ! [[ $value =~ $expr ]]
 			then
@@ -100,12 +127,15 @@ getConfigDestination() {
 					destinationloss["$destination"]="$value"
 				;;
 				*)
-					echo "$Invalid parameter \"$key\" for format \"${destinationformat["$destination"]}\"" >&2
+					echo "Invalid parameter '$key' for" \
+					"format"			    \
+					"'${destinationformat["$destination"]}'" >&2
 					exit $EFMTINVPARM
 				;;
 			esac
 		;;
 		'channels')
+			# Up/downmix to this many channels if needed
 			expr='^[0-9]*$'
 			if ! [[ $value =~ $expr ]]
 			then
@@ -116,6 +146,7 @@ getConfigDestination() {
 			destinationchannels["$destination"]=$value
 		;;
 		'frequency')
+			# Resample to this sample rate in Hz (e.g. 44100)
 			expr='^[0-9]*$'
 			if ! [[ $value =~ $expr ]]
 			then
@@ -126,21 +157,24 @@ getConfigDestination() {
 			destinationfrequency["$destination"]=$value
 		;;
 		'noresample')
+			# MP3-only: prevent lame from auto-downsampling at low
+			# bitrates
 			case $value in
-				'true'|'on'|'yes')
+				'true'|'on'|'yes'|'1')
 					destinationnoresample["$destination"]=1
 				;;
-				'false'|'off'|'no')
+				'false'|'off'|'no'|'0')
 					destinationnoresample["$destination"]=0
 				;;
 				*)
 					echo "noresample takes values:"	\
-					"'yes' ,'true' ,'on', 'no', 'false',"\
+					"'yes' ,'true' ,'on', '1', 'no',"\
-					"'off'"
+					"'false','off', '0'"
 				;;
 			esac
 		;;
 		'rename')
+			# File rename pattern using %{tag} tokens
 			case "$value" in
 				*/*)
 					destinationrenamepath["$destination"]="${value%/*}"
@@ -149,46 +183,62 @@ getConfigDestination() {
 			destinationrename["$destination"]="${value##*/}"
 		;;
 		'fat32compat')
+			# Strip FAT32-illegal characters (? \ < > : * | ")
+			# trim spaces/dots
 			case $value in
-				'true'|'on'|'yes')
+				'true'|'on'|'yes'|'1')
 					destinationfat32compat["$destination"]=1
 				;;
-				'false'|'off'|'no')
+				'false'|'off'|'no'|'0')
 					destinationfat32compat["$destination"]=0
 				;;
 				*)
-					echo "fat32compat takes values:"	\
+					echo "fat32compat takes values:" \
-					"'yes' ,'true' ,'on', 'no', 'false',"\
+					"'yes' ,'true' ,'on', '1', 'no',"\
-					"'off'"
+					"'false','off', '0'"
 				;;
 			esac
 		;;
 		'ascii-only')
+			# Transliterate Unicode filenames to ASCII using
+			#Requires Perl Text::Unidecode
 			case $value in
-				'true'|'on'|'yes')
+				'true'|'on'|'yes'|'1')
 					destinationascii["$destination"]=1
+					# Signal that the perl coprocess will
+					# be needed
 					textunidecodeneeded=1
 				;;
-				'false'|'off'|'no')
+				'false'|'off'|'no'|'0')
 					destinationascii["$destination"]=0
 				;;
 				*)
 					echo "ascii-only takes values:"	\
-					"'yes' ,'true' ,'on', 'no', 'false',"\
+					"'yes' ,'true' ,'on', '1', 'no',"\
-					"'off'"
+					"'false','off', '0'"
 				;;
 			esac
 		;;
 		'skip_mime-type')
+			# Accumulate pipe-separated list of mime patterns to
+			# exclude entirely
 			destinationskipmime[$destination]="${destinationskipmime[$destination]:+${destinationskipmime[$destination]}|}$value"
 		;;
 		'copy_mime-type')
+			# Accumulate pipe-separated list of mime patterns to
+			# copy verbatim (action=2)
 			destinationcopymime[$destination]="${destinationcopymime[$destination]:+${destinationcopymime[$destination]}|}$value"
 		;;
 		'copy_extension')
+			# Accumulate pipe-separated list of file extensions to
+			# copy verbatim
 			destinationcopyext[$destination]="${destinationcopyext[$destination]:+${destinationcopyext[$destination]}|}$value"
 		;;
 		'higher-than')
+			# Only re-encode source files with bitrate ABOVE this
+			# threshold (kbps)
+			# Files at or below this bitrate will be
+			# hardlinked/copied instead
 			expr='^[0-9]*$'
 			if ! [[ $value =~ $expr ]]
 			then

lib/config/getGeneral

@@ -1,7 +1,23 @@
 #!/bin/bash
+
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 getConfigGeneral() {
 	case $key in
 		'max-load')
+			# Target system 1-minute load average
+			# concurrency is adjusted to stay near this
 			expr='^[0-9]*$'
 			if [[ $value =~ $expr ]]
 			then
@@ -13,6 +29,7 @@ getConfigGeneral() {
 			unset expr
 		;;
 		'load-interval')
+			# How often (seconds) to adjust worker count
 			expr='^[0-9]*$'
 			if [[ $value =~ $expr ]]
 			then
@@ -48,6 +65,7 @@ getConfigGeneral() {
 						fi
 					;;
 					2)
+						# Best-effort class; niceness 0 (highest) to 7 (lowest)
 						if [ -n "$niceness" ]		\
 						&& (( niceness >= 0 && niceness <= 7 ))
 						then
@@ -59,10 +77,11 @@ getConfigGeneral() {
 						fi
 					;;
 					3)
+						# Idle class: only gets I/O when no other process needs it
 						ionice="ionice -c3 "
 					;;
 					*)
-						echo "Invalid ionice parameters $value"\
+						echo "Invalid ionice class $value"\
 						>&2
 						exit $EIONICE
 					;;
@@ -70,15 +89,23 @@ getConfigGeneral() {
 			fi
 		;;
 		'temporary-directory')
+			# Directory for
+			# * SQLite FIFOs
+			# * intermediate WAV files
+			# * debug logs
 			tempdir="$value"
 		;;
 		'database')
+			# Path to the SQLite database file
 			database="$value"
 		;;
 		'skip-timestamp-microsec')
+			# If non-zero, ignore sub-second precision in file timestamps
+			# Useful on filesystems that don't preserve microseconds
 			skip_us_timestamp="$value"
 		;;
 		debug)
+			# Allow config file to raise debug level (but not lower it)
 			(( value > debug )) && debug=$value
 		;;
 	esac

lib/config/getSource

@@ -1,10 +1,27 @@
 #!/bin/bash
+
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 getConfigSource() {
 	case "$key" in
 		'path')
+			# Root directory of music collection to transcode from
 			sourcepath="$value"
 		;;
 		'skip')
+			# Directory pattern to exclude from scanning
+			# Multiple 'skip' entries accumulate into this array
 			skippeddirectories+=( "$value" )
 		;;
 	esac

lib/config/print

@@ -1,6 +1,22 @@
 #!/bin/bash
+
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 printConfig() {
 	{
+		# Build a pipe-delimited table
+		# 'column -t -s|' will transform into columns
 		echo "General|Config file|$cffile"
 		[ -n "$ionice" ] && echo "|IO Nice|$ionice"
 		cat <<-EOF
@@ -12,24 +28,29 @@ printConfig() {
 
 			Source|Path|$sourcepath
 		EOF
+		# Print skipped directories
+		# use a continuation prefix after the first
 		for prune_expression in "${skippeddirectories[@]}"
 		do
-			(( printed ))				\
+			(( printed ))					\
 			&& echo -n ' | |'				\
 			|| echo -n ' |Skipped directories|'
 			echo "$prune_expression"
 			printed=1
 		done
 		unset printed
+		# Loop over destinations and print their settings
+		# use the destination name as a key into the associative arrays
 		for destination in ${destinations[@]}
 		do
 			cat <<-EOF
- 
+
 				$destination|Path|${destinationpath["$destination"]}
 				 |Enabled|${destinationenabled["$destination"]}
 				 |Format|${destinationformat["$destination"]}
 				 |Quality|${destinationquality["$destination"]}
 			EOF
+			# Show format-specific fields
 			if [[ ${destinationformat["$destination"]} == opus ]]
 			then
 				echo " |Expected loss|${destinationloss["$destination"]}"
@@ -47,6 +68,7 @@ printConfig() {
 				 |Path Change|${destinationrenamepath["$destination"]}
 				 |File Rename|${destinationrename["$destination"]}
 			EOF
+			# Display pipe-separated mime lists: one entry per row
 			[ -n "${destinationskipmime["$destination"]}" ]	\
 			&& echo " |Skipped mime-types|${destinationskipmime["$destination"]//\|/
 | |}"
@@ -57,5 +79,5 @@ printConfig() {
 			&& echo " |Copied extensions|${destinationcopyext["$destination"]//\|/
 | |}"
 		done
-	}|column -t -s'|'
+	}|column -t -s'|' # Format as aligned columns using '|' as delimiter
 }

lib/config/write

@@ -1,5 +1,22 @@
 #!/bin/bash
 
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
+
+# writeConfig() generates a new atom.cfg from the current in-memory settings.
+# Output is sent to stdout so callers can redirect it to any config file path.
+# Each setting is annotated with a description.
 writeConfig() {
 	cat <<-EOCfg
 [general]
@@ -47,6 +64,7 @@ path			$sourcepath
 # * skip <directory>: String. Files in <directory> will be ignored. Note that
 #     <directory> can be any expression accepted by find.
 	EOCfg
+	# Emit one skip line per skipped directory
 	for dir in "${skippeddirectories[@]}"
 	do
 		echo $'skip\t\t\t'"$dir"
@@ -55,6 +73,7 @@ path			$sourcepath
 
 
 	EOCfg
+	# Emit one section per configured destination
 	for destination in "${destinations[@]}"
 	do
 		cat <<-EOCfg
@@ -190,6 +209,8 @@ bitrate			${destinationquality["$destination"]}
 #     be included in that destination. For more than one mime-type, use multiple
 #     times, as needed. The '*' character is a wildcard.
 		EOCfg
+		# Emit one skip_mime-type line per MIME pattern (pipe-separated
+		# in the array)
 		destinationskipmime["$destination"]="${destinationskipmime["$destination"]}|"
 		while [[ ${destinationskipmime["$destination"]} =~ \| ]]
 		do
@@ -203,6 +224,7 @@ bitrate			${destinationquality["$destination"]}
 #     covers and other images to the destination. In fact, AtOM will try to use
 #     hard links instead of copies.
 		EOCfg
+		# Emit one copy_mime-type line per MIME pattern
 		destinationcopymime["$destination"]="${destinationcopymime["$destination"]}|"
 		while [[ ${destinationcopymime["$destination"]} =~ \| ]]
 		do
@@ -213,6 +235,7 @@ bitrate			${destinationquality["$destination"]}
 
 #   * copy_extension <extension>: Copy files whose name and with ".<extension>"
 		EOCfg
+		# Emit one copy_extension line per extension pattern
 		destinationcopyext["$destination"]="${destinationcopyext["$destination"]}|"
 		while [[ ${destinationcopyext["$destination"]} =~ \| ]]
 		do

lib/copy/action

@@ -1,6 +1,25 @@
 #!/bin/bash
+
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 copyFiles_action() {
 	(( cron )) || echo -n $'Copying files...\033[K'
+	# Query all destination_files whose last_change doesn't match the
+	# source, restricted to mime_type_actions with action=2 (direct copy,
+	# not transcode).
+	# The join on mime_type_actions ensures we only copy files destined for
+	# a destination that has explicitly mapped this MIME type to action=2.
 	echo '
 		SELECT
 			source_files.filename,
@@ -22,6 +41,8 @@ copyFiles_action() {
 		AND	mime_type_actions.action = 2;
 
 		SELECT "AtOM:NoMoreFiles";' >&3
+	# Results are NUL-delimited rows; sentinel value signals end of result
+	# set.
 	read -u4 -r -d $'\0' line
 	while ! [[ $line = AtOM:NoMoreFiles ]]
 	do
@@ -29,9 +50,14 @@ copyFiles_action() {
 		read -u4 -r -d $'\0' line
 	done
 
+	# Wrap all DB updates in a single transaction for performance.
 	echo 'BEGIN TRANSACTION;' >&3
 	for copyfile in "${copyfiles[@]}"
 	do
+		# Each row is a single string with columns joined by
+		# ::AtOM:SQL:Sep::.
+		# Strip prefix to extract each field in order, advancing $rest
+		# each time.
 		sourcefilename=${copyfile%%::AtOM:SQL:Sep::*}
 		sourcedir=${sourcefilename%/*}
 		rest="${copyfile#*::AtOM:SQL:Sep::}::AtOM:SQL:Sep::"
@@ -45,20 +71,33 @@ copyFiles_action() {
 		rest=${rest#*::AtOM:SQL:Sep::}
 		(( count++ ))
 		(( cron )) || printf '\b\b\b\b%3i%%' $(( (count * 100) / ${#copyfiles[@]} ))
+		# If this destination uses a rename/path pattern, delegate path
+		# resolution to guessPath(), which looks up the
+		# already-transcoded sibling to find the correct output
+		# directory.
 		if [ -n "${destinationrenamepath["$destination"]}" ]
 		then
 			destdir="$(guessPath)"
 			guessstatus=$?
 			case $guessstatus in
 				1)
+					# guessPath found no transcoded
+					# sibling; skip this file entirely.
 					continue
 				;;
 				2)
+					# Transcoded siblings exist but are not
+					# yet up to date; defer this copy until
+					# the next run so the directory is
+					# stable.
 					(( postponed++ ))
 					continue
 				;;
 			esac
 		else
+			# No rename pattern: mirror the source directory
+			# structure under the destination root, sanitizing each
+			# path component for the target FS.
 			destdir="${destinationpath["$destination"]}/"
 			if [[ $sourcefilename =~ / ]]
 			then
@@ -79,6 +118,9 @@ copyFiles_action() {
 				fi
 			fi
 		fi
+		# Try the cheapest copy methods first: reflink (CoW, same
+		# filesystem), then hardlink (csame filesystem), falling back
+		# to a full data copy.
 		if cp -a --reflink=always		\
 			"$sourcepath/$sourcefilename"	\
 			"$destdir"			\
@@ -91,6 +133,9 @@ copyFiles_action() {
 			"$sourcepath/$sourcefilename"	\
 			"$destdir"
 		then
+			# Newlines in filenames are stored as a safe inline
+			# placeholder so the value can be embedded in SQL
+			# without breaking row parsing.
 			destfilename=${sourcefilename//$'\n'/::AtOM:NewLine:SQL:Inline::}
 			Update destination_files			\
 				filename				\

lib/copy/check

@@ -1,12 +1,39 @@
 #!/bin/bash
+
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 checkCopy() {
+	# Returns true only when the source file is compatible enough with the
+	# destination profile that it can be copied instead of re-encoded.
+	# All three conditions must hold simultaneously.
 	(
+		# If the destination doesn't restrict sample rate, any rate is
+		# acceptable. Otherwise the source rate must match exactly.
 		[ -z "${destinationfrequency[$destination]}" ]		\
 		|| (( ${rate:-0} == ${destinationfrequency[$destination]} ))
 	) && (
+		# If the destination doesn't restrict channel count, any number
+		# is acceptable. Otherwise the source channel count must match
+		# exactly.
 		[ -z "${destinationchannels[$destination]}" ]		\
 		|| (( ${channels:-0} == ${destinationchannels[$destination]} ))
 	) && (
+		# Bitrate check: accept if source exactly matches the target
+		# quality setting, OR if a maximum bps ceiling is configured
+		# and the source bitrate is at or below it.
+		# Default of 1000 kbps when bitrate is unknown forces a
+		# re-encode
 		(( ${bitrate:-1000} == ${destinationquality[$destination]} ))	\
 		|| (
 			[ -n "${destinationmaxbps[$destination]}" ]	\

lib/copy/guessPath

@@ -1,6 +1,29 @@
 #!/bin/bash
 
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 guessPath() {
+	# For copy files (action=2) with a rename pattern, we don't know the
+	# output directory ourselves: it was determined when the audio siblings
+	# were transcoded (action=1). We infer it by finding a transcoded
+	# sibling in the same source directory and reading back its destination
+	# path.
+	#
+	# First query: check whether any transcoded sibling is up to date.
+	# The LIKE pattern matches files directly inside $sourcedir only
+	# the NOT LIKE excludes deeper subdirectorie to avoid crossing
+	# boundaries.
 	echo 'SELECT IFNULL( (
 		SELECT	destination_files.last_change
 		FROM		destination_files
@@ -22,10 +45,17 @@ guessPath() {
 	),"0.0");
 	'>&3
 	read -u4 -r -d $'\0' timestamp
+	# IFNULL returns "0.0" when no transcoded sibling exists yet; strip the
+	# decimal and treat as zero to detect the no-sibling case.
 	if (( ${timestamp/./} == 0 ))
 	then
+		# No transcoded sibling found at all
+		# caller should postpone this copy.
 		return 2
 	fi
+	# Second query: retrieve the actual destination filename of the most
+	# recently updated transcoded sibling so we can derive its parent
+	# directory.
 	echo 'SELECT IFNULL( (
 		SELECT	destination_files.filename
 		FROM		destination_files
@@ -49,8 +79,12 @@ guessPath() {
 	read -u4 -r -d $'\0' filename
 	if [[ $filename != AtOM:NotFound ]]
 	then
+		# Strip the filename component to return only the directory
+		# portion.
 		echo "${filename%/*}"
 	else
+		# Sibling record exists but has no usable filename — skip this
+		# file.
 		return 1
 	fi
 }

lib/copy/matching

@@ -1,6 +1,25 @@
 #!/bin/bash
+
+# Copyright © 2012-2026 ScriptFanix
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# A copy of the GNU General Public License v3 is includded in the LICENSE file
+# at the root of the project.
+
 copyFiles_matching() {
+	# Preserve the original file extension so the copy keeps its type
+	# (e.g. .jpg, .png, .cue) regardless of any rename pattern applied to
+	# the base name.
 	local extension="${filename##*.}"
+	# Try hardlink first (no extra disk space); fall back to a full data
+	# copy if the source and destination are on different filesystems.
 	if					\
 	cp -al					\
 		"$sourcepath/$filename"		\
@@ -10,6 +29,11 @@ copyFiles_matching() {
 		"$sourcepath/$filename"		\
 		"${destinationpath[$destination]}/$destdir/$destfile.$extension"
 	then
+		# Record the new destination path and copy the source
+		# last_change timestamp via a subquery so the DB reflects when
+		# the source was last modified.
+		# old_filename captures the previous path so stale files can be
+		# cleaned up later.
 		echo							\
 			"UPDATE	destination_files"			\
 			"SET filename="					\