Media Format Converter

A local-first media converter for common video and audio formats. The browser app runs conversion in WebAssembly without uploading files; the existing CLI and Colab workflows remain available for MP4 to MP3.

Features

Single File Conversion: Convert one MP4 file at a time
Batch Conversion: Convert multiple MP4 files in one go
Cross-Platform: Works on Windows, macOS, Linux, and Google Colab
High Quality: Uses 192kbps bitrate for excellent audio quality
User-Friendly: Interactive CLI interface with clear prompts
Automatic Setup: Auto-installs dependencies on Google Colab
Browser Converter: Convert common video/audio files locally in a web browser with WebAssembly
Browser Queue Controls: Remove queued items, convert one item, retry failures, or process the remaining queue in batch
Batch Downloads: Download completed results individually or as one ZIP archive
Configurable Bitrate: Choose 128, 192, 256, or 320 kbps for the next browser conversion
Theme and Language Preferences: Switch between dark/light themes and Traditional Chinese/English; preferences are saved in the browser
Loudness Normalization: Optionally apply FFmpeg loudnorm during conversion so audio output has a more consistent playback level

Requirements

Local Installation

Python 3.7+
ffmpeg
ffmpeg-python

Google Colab

No prerequisites needed - all dependencies are automatically installed!

Installation

Local Setup

Clone or download this repository
Install Python dependencies
```
pip install -r requirements.txt
```

Install ffmpeg

Windows - Option 1: Using Chocolatey (Recommended)

# First, install Chocolatey (run as Administrator)
Set-ExecutionPolicy Bypass -Scope Process -Force; `
[System.Net.ServicePointManager]::SecurityProtocol = `
    [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; `
iex ((New-Object System.Net.WebClient).DownloadString(
    'https://chocolatey.org/install.ps1'))

# Then install ffmpeg
choco install ffmpeg

Windows - Option 2: Using winget

winget install ffmpeg

Windows - Option 3: Manual Installation

Download from: https://www.gyan.dev/ffmpeg/builds/
Extract and add the bin folder to your system PATH

macOS

brew install ffmpeg

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install ffmpeg

Linux (CentOS/RHEL)

sudo yum install ffmpeg

Verify installation
```
ffmpeg -version
```

Usage

Local Usage

Run the converter
```
python converter.py
```
Choose conversion mode
- Option 1: Single file conversion
- Option 2: Batch conversion
Single File Mode
- Enter the path to your MP4 file
- Optionally specify an output filename
- The MP3 file will be saved in the same directory
Batch Mode
- Enter a directory path or file pattern (e.g., *.mp4 or /path/to/videos/)
- Optionally specify an output directory
- All MP4 files will be converted to MP3

Google Colab Usage

Option 1: One-Click Version (Recommended)

The easiest way to use this tool - everything runs in a single cell!

Open the one-click notebook:
Run the single cell (click the play button or press Shift+Enter)
That's it! The notebook will:
- Install all dependencies automatically
- Prompt you to upload MP4 files
- Convert all files to MP3
- Download the MP3 files automatically
- Clean up temporary files

No need to run multiple cells - everything happens automatically!

Option 2: Step-by-Step Version

For more control over the conversion process:

Open the step-by-step notebook:
Run the cells in order:
- Cell 1: Setup - Installs ffmpeg and dependencies
- Cell 2: Load Functions - Loads converter functions
- Cell 3: Upload Files - Upload your MP4 files
- Cell 4: Single File Conversion (Optional)
- Cell 5: Batch Conversion (Optional)
- Cell 6: Download - Download converted MP3 files
- Cell 7: Cleanup (Optional) - Remove files from Colab
Tips for Colab:
- You can upload multiple files at once
- Remember to download your MP3 files before closing the notebook
- Colab has file size limits (typically 100MB per file for free tier)

Browser Usage

The browser converter lives in web/ and uses pinned ffmpeg.wasm packages with a Vite build. Conversion runs locally in the browser; selected files are not sent to a backend or cloud storage service.

Supported browser inputs

The first browser-supported input matrix covers common containers and codecs by file extension:

Video: .mp4, .webm, .mov, .mkv, .avi, .m4v, .ogv, .mpeg, .mpg, .ts
Audio: .mp3, .wav, .m4a, .aac, .flac, .ogg, .oga, .opus

The extension is used to give FFmpeg.wasm a useful input filename. A matching extension does not guarantee that an unusual or damaged file can be decoded.

Browser outputs

Audio: MP3, M4A/AAC, WAV, FLAC, OGG/Vorbis, and Opus
Video: MP4/H.264 + AAC and WebM/VP8 + Opus, for video inputs only

Video output is a full browser-side transcode and can be substantially slower and more memory-intensive than extracting audio. DRM/protected streams, unsupported codecs, and files that exceed the device's practical memory are not supported.

Workflow

Select or drag one or more supported video/audio files into the queue.
Choose an output format. Video outputs are disabled when the queue contains an audio-only input.
Optionally enable loudness normalization in Output Settings. It applies to the next conversion, including audio tracks in video output.
Load the local WebAssembly converter the first time you use the page.
Use Convert on an individual queue item, or use Start batch conversion to process all queued and failed items sequentially.
Remove queued, failed, or completed items with Remove; the item currently being converted stays locked until it finishes.
Download each completed result, or use Download all to download all completed files as one ZIP archive.

The header language selector switches between Traditional Chinese and English. The adjacent theme control switches between dark and light mode; both preferences persist in the current browser.

The browser UI does not impose a hard file-size cap. Files larger than 250 MiB show a memory warning because browser conversion may require several times the input size in working memory; the practical limit depends on the device and browser.

Local Development

npm install
npm run dev

The production build is generated with:

npm run build

The Pages workflow builds the site and deploys the generated docs/ directory when changes reach main.

Examples

Local Example 1: Convert a single file

$ python converter.py

==================================================
多媒體格式轉換器 - MP4 to MP3
==================================================

請選擇模式：
1. 單一檔案轉換
2. 批次檔案轉換
請輸入選項 (1 或 2): 1

請輸入 MP4 檔案路徑: video.mp4
請輸入輸出 MP3 檔案名稱 (留空則使用預設名稱):

開始轉換: video.mp4 -> video.mp3
✓ 轉換完成: video.mp3

轉換成功！

Local Example 2: Batch convert all files in a directory

$ python converter.py

請選擇模式：
1. 單一檔案轉換
2. 批次檔案轉換
請輸入選項 (1 或 2): 2

批次轉換模式
提示：可以輸入資料夾路徑或檔案模式 (例如: *.mp4 或 /path/to/videos/)
請輸入檔案路徑或模式: /path/to/videos/
請輸入輸出目錄 (留空則輸出到原檔案位置):

找到 5 個檔案
是否跳過已存在的檔案？ (y/n, 預設為 y): y

[1/5] 處理: video1.mp4
開始轉換: video1.mp4 -> video1.mp3
✓ 轉換完成: video1.mp3

[2/5] 處理: video2.mp4
開始轉換: video2.mp4 -> video2.mp3
✓ 轉換完成: video2.mp3

...

==================================================
批次轉換完成！
成功: 5 個檔案
失敗: 0 個檔案
跳過: 0 個檔案
==================================================

Colab Example

# After running setup cells and uploading files:

# Convert all uploaded files
success, fail, skip = batch_convert("*.mp4")
# Output:
# Found 3 file(s)
# [1/3] Processing: vacation.mp4
# Converting: vacation.mp4 -> vacation.mp3
# ✓ Conversion completed: vacation.mp3
# ...

Troubleshooting

Issue: "找不到 ffmpeg" / "ffmpeg not found"

Solution: Install ffmpeg following the installation instructions above. Make sure to restart your terminal/PowerShell after installation.

Issue: Conversion fails with encoding errors

Solution: Ensure your MP4 file is not corrupted. Try playing it in a video player first.

Issue: Python package import errors

Solution: Reinstall the required packages:

pip install --upgrade ffmpeg-python

Issue: Permission denied errors on Windows

Solution: Run PowerShell as Administrator when setting environment variables.

Colab Issue: Upload fails or times out

Solution:

Check your file size (Google Colab has limits)
Try uploading fewer files at once
Check your internet connection

File Structure

MediaFormatConverter/
├── converter.py                              # Main CLI converter script
├── MediaFormatConverter_Colab.ipynb          # Google Colab notebook (step-by-step)
├── MediaFormatConverter_Colab_OneClick.ipynb # Google Colab notebook (one-click)
├── requirements.txt                          # Python dependencies
├── spec.md                                   # Project specification
└── README.md                                 # This file

Browser application files:

web/ - browser converter source
package.json and package-lock.json - frontend dependencies and scripts
scripts/copy-ffmpeg-core.mjs - copies the pinned local WASM core into the build
vite.config.js - Vite configuration
.github/workflows/pages.yml - Pages build and deployment workflow

Technical Details

Browser engine: @ffmpeg/core 0.12.10 through ffmpeg.wasm
Audio encoders: libmp3lame, native AAC, PCM, FLAC, libvorbis, and libopus
Audio processing: Optional loudnorm loudness normalization targets a consistent integrated level for each converted file
Video encoders: libx264 for MP4 and libvpx for WebM
MP3 bitrate: Browser presets 128/192/256/320 kbps; 192 kbps is the default
Sample rate/channels: Preserved where the selected output format permits it
Privacy: Files stay in browser memory and are not uploaded by the application

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This project is open source and available under the MIT License.

Changelog

Version 1.0.0

Initial release
Single file conversion
Batch conversion
CLI interface
Google Colab support
Automatic dependency installation for Colab
File upload/download support for Colab

Support

If you encounter any issues or have questions:

Check the Troubleshooting section above
Search existing issues
Create a new issue with detailed information about your problem

Acknowledgments

Built with ffmpeg
Uses ffmpeg-python
Designed for both local and Google Colab environments

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
scripts		scripts
web		web
.gitignore		.gitignore
LICENSE		LICENSE
MediaFormatConverter_Colab.ipynb		MediaFormatConverter_Colab.ipynb
MediaFormatConverter_Colab_OneClick.ipynb		MediaFormatConverter_Colab_OneClick.ipynb
README.md		README.md
converter.py		converter.py
package-lock.json		package-lock.json
package.json		package.json
requirements.txt		requirements.txt
spec.md		spec.md
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation