Technical Documentation: Audio to Video Converter

This document provides a technical breakdown of the "Audio to Video Converter," a Python application built with tkinter. The application serves as a user-friendly graphical interface for the powerful command-line tool FFmpeg, allowing users to easily convert multiple audio files into videos by pairing them with a static image.

Core Technologies ⚙️

The application is built entirely in Python and leverages several key libraries and modules to achieve its functionality:

• Tkinter: This is Python's standard GUI (Graphical User Interface) library. It's used to create all the visual elements of the application, including the main window, buttons, listbox, labels, and progress bars. The ttk themed widgets are used for a more modern look and feel.
• Subprocess: This module is essential for running and managing the external FFmpeg process. It allows the Python script to execute command-line operations, capture their output (stdout and stderr), and monitor their status.
• Threading: To prevent the user interface from freezing during the time-consuming video conversion process, the core FFmpeg operations are run in a separate background thread. This ensures the application remains responsive, allowing the user to see real-time progress updates and even cancel the operation.
• Queue: This module provides a thread-safe queue, which is used as a communication channel between the background conversion thread and the main GUI thread. Log messages generated by the FFmpeg process are placed into the queue by the background thread and safely retrieved by the main thread to be displayed in the logs window.
• Imageio-ffmpeg: This helper library is used for a single, crucial purpose: to automatically locate the FFmpeg executable on the user's system. This removes the need for the user to manually configure the path to FFmpeg.
• OS & Re: The os module is used for file system operations, like extracting filenames from full paths, while the re (regular expression) module is used to parse text output from FFmpeg to determine video duration and conversion progress.

Architecture and Workflow 🏗️

The application is encapsulated within a single class, YouTubeAudioBatchConverter, which manages the application's state, UI, and logic.

1. Initialization & UI Setup

When the application starts, the __init__ constructor:

1. Initializes the main tkinter window (self.root).
2. Sets up a ttk.Style for the UI elements.
3. Initializes state variables, such as self.audio_files, self.image_file, and self.output_dir.
4. Calls self.create_widgets() to build the entire user interface as shown in the screenshot. The UI is logically divided into frames: a top toolbar, a file info section, a controls row, progress bars, and a logs console.
5. Starts a recurring check of the log_queue via self.process_log_queue, allowing messages from other threads to be displayed in the UI.

2. User Interaction

The user interacts with the application through the buttons in the toolbar:

• [+ Audio], [Image...], [Output...]: These buttons trigger filedialog prompts, allowing the user to select input files and an output directory. The selections are stored in the class variables and the UI labels are updated accordingly.
• [− Remove], [× Clear]: These buttons manage the list of audio files to be processed, modifying both the internal self.audio_files list and the visible audio_listbox.

3. The Conversion Process

This is the core logic of the application, handled by a background thread to keep the GUI responsive.

1. Start Conversion: Clicking the ▶ Start button calls the start_conversion method. This method first validates that an audio file, an image, and an output directory have all been selected. It then disables the "Start" button, enables the "Cancel" button, and launches the run_batch_conversion method in a new daemon thread.
2. Batch Processing: The run_batch_conversion method iterates through each audio file selected by the user. For each file, it constructs and executes a specific FFmpeg command.
3. The FFmpeg Command: The script programmatically builds the following command for each conversion:

   ffmpeg -y -i "audio_file.mp3" -loop 1 -i "image_file.png" -c:v libx264 -tune stillimage -c:a aac -b:a 192k -pix_fmt yuv420p -shortest -vf "scale=...:pad=..." "output_file.mp4"

   • -y: Automatically overwrites the output file if it exists.
   • -i "audio_file.mp3": Specifies the input audio file.
   • -loop 1 -i "image_file.png": Specifies the input image and loops it indefinitely.
   • -c:v libx264 -tune stillimage: Uses the efficient H.264 video codec, optimized for static images.
   • -c:a aac -b:a 192k: Uses the AAC audio codec with a bitrate of 192 kbps.
   • -pix_fmt yuv420p: Sets the pixel format to ensure compatibility across most players and platforms.
   • -shortest: Ensures the video output duration matches the shorter of the inputs (in this case, the audio file).
   • -vf "...": Applies a video filter to scale the image to fit within a 1920x1080 frame, adding black bars (padding) if necessary to maintain the aspect ratio.
4. Execution and Progress Tracking:
   • Before running the main command, the get_audio_duration method runs a separate, quick ffmpeg -i command. It parses the command's text output with a regular expression to find the audio file's total duration.
   • The main FFmpeg command is then executed using subprocess.Popen. This is crucial as it allows the script to read the command's output streams (stdout and stderr) in real-time.
   • As FFmpeg processes the file, it prints progress updates to its stderr stream, which look like time=00:01:23.45 .... The run_ffmpeg method reads these lines one by one.
   • A regular expression (time_re) is used to extract the current timestamp from the progress line.
   • This timestamp is converted to seconds and compared against the total duration to calculate a percentage progress.
   • The file_progress bar is updated. Critically, this UI update is sent to the main thread using self.root.after(), as directly modifying tkinter widgets from a secondary thread is not safe.

4. Logging and Completion

• Thread-Safe Logging: All output from the FFmpeg process (both progress and other information) is not written directly to the log window. Instead, the log() method places the message string into self.log_queue. The process_log_queue method, running on the main GUI thread, periodically checks this queue for new messages and safely inserts them into the scrolledtext widget. This prevents race conditions and ensures smooth UI updates.
• Cancellation: If the user clicks ⏹ Cancel, the self.cancelled flag is set to True, and the self.process.kill() method immediately terminates the running FFmpeg process.
• Completion: Once the loop finishes (or is cancelled), the UI buttons are returned to their original state. If the process completed successfully, a confirmation message is displayed.