🎵 My Jam

My Jam is a versatile audio converter built on ffmpeg with both CLI and web GUI interfaces.

It supports common ringtone and streamed audio formats including:

• MP3
• WAV
• OGG
• AAC
• AMR
• QCP

Plus additional modern formats:

• M4A
• FLAC
• OPUS

Designed for batch conversion, ringtone creation, trimming, normalization, denoising, metadata management, and format standardization.

---

Two Ways to Use My Jam

My Jam can be used in two ways:

Feature	CLI (Command Line Interface)	GUI (Web User Interface)
Best for	Power users, automation, batch scripts	Quick conversions, visual feedback
Interface	Terminal commands	Web browser
File selection	File paths	File picker dialog
Output	Save to directory	Download to chosen location
Setup	Python + ffmpeg	Docker

Choose the option that best fits your workflow:

• CLI: Full control, scriptable, useful for automation.

• GUI: User-friendly, no command-line needed, visual feedback.

---

Quick Start

CLI Usage

python myjam.py input.wav -t mp3

GUI Usage

docker compose up -d
# Open http://localhost:8080 in your browser

---

Getting Started with the GUI

Prerequisites

• Docker installed and running

• Docker Compose

Installation & Setup

1. Clone the repository (if you haven't already):

git clone https://github.com/HelixCipher/myjam.git
cd myjam

2. Start the GUI with Docker:

docker compose up -d

3. Access the GUI: Open your browser and navigate to:

http://localhost:8080

That's it. The GUI is now running and ready to use.

Stopping the GUI

docker compose down

To remove the application and user data:

docker compose down -v

---

GUI User Guide

Interface Overview

The GUI is divided into several sections:

1. Format Selector (left sidebar) - Choose your target format.

2. Options Panel (center) - Configure conversion settings.

3. Conversion Jobs - See progress and download results.

---

Selecting Files

1. Click the "Choose File" button in the Input File section.

2. Select an audio or video file from your computer.

3. The selected file will be displayed with its name and size.

4. You can also select multiple files and add them to the queue.

---

Format Selection

In the left sidebar, choose your target format:

Format	Best For
MP3	Universal compatibility
WAV	Lossless, high quality
OGG	Open format, good compression
M4A/AAC	Apple devices, streaming
FLAC	Lossless archiving
OPUS	High compression, voice
AMR	Telephony/ringtones
QCP	Legacy format

You can select multiple formats. When downloading, if you selected multiple formats, all converted files will be downloaded as a single ZIP archive. If you selected only one format, the single file will be downloaded directly.

---

Mode Toggles

Ringtone Mode

• What it does: Automatically optimizes for mobile ringtones.

• Defaults: 30 seconds, 128k bitrate, 44.1kHz sample rate.

• Useful for: Creating phone ringtones from longer tracks.

• How to use: Toggle the "Ringtone Mode" switch

Video to MP3

• What it does: Extracts audio from video files.

• Best for: Converting video soundtracks to audio.

• How to use: Toggle the "Video to MP3" switch.

• Supported input: MP4, AVI, MOV, MKV, WebM, and more.

---

Trim & Effects

Start Time / Duration

• Start (s): Begin conversion at a specific time (in seconds).

• Duration (s): Keep only a portion of the audio.

• Example: Start at 30, Duration 30 - converts seconds 30-60.

Fade In / Fade Out

• Fade In: Gradually increase volume at the start.

• Fade Out: Gradually decrease volume at the end.

• Use case: Create smooth transitions, avoid harsh cuts.

Normalize Audio

• What it does: Automatically adjusts volume to optimal levels.

• Useful for: Ensuring consistent volume across tracks.

• How to use: Toggle the "Normalize audio" switch.

---

Denoise

Reduce background noise from recordings:

Setting	Description	Default
Enable denoising	Turn on noise reduction	Off
Noise sample (s)	Seconds at start to analyze as noise	0.5
Threshold	Higher = less aggressive	1.5
Noise reduction strength	0 = subtle, 1 = aggressive	1.0

Tip: For typical recordings, the defaults work well. Adjust for more challenging noise.

---

Metadata

Control what information is stored in the converted files:

Option	Description
Strip all metadata	Remove all ID3 tags, album art, etc.
Title from filename	Use filename as title tag
Artist from filename	Try to extract artist from filename
Custom title	Manually set the title
Custom artist	Manually set the artist

Privacy tip: Use "Strip all metadata" to remove personal information before sharing files.

---

Advanced Settings

Setting	Description
Bitrate	Audio quality (e.g., 128k, 192k, 256k, 320k)
Sample rate	Hz (e.g., 44100, 48000)
Channels	1 = Mono, 2 = Stereo
Recursive	Include subfolders (CLI only)
Overwrite	Replace existing files
Dry run	Preview without converting
Verbose	Show detailed output
Workers	Parallel conversions (1-8)

---

Converting a File

1. Select a file using the file picker.

2. Choose output format from the left sidebar.

3. Configure options (ringtone, denoise, trim, etc.).

4. Click "Convert Now".

5. Wait for the conversion to complete (green checkmark appears).

6. Click the download button to save your converted file.

---

Downloading Your Converted File

When conversion completes:

1. A download button appears next to the job.

2. Click it to download the converted file.

3. Your browser's "Save As" dialog will open.

4. Choose where to save the file on your computer.

Multiple Formats: If you selected more than one output format (e.g., MP3 + WAV + OGG), clicking the download button will create a ZIP archive containing all converted files. Your browser's "Save As" dialog will let you choose where to save the ZIP file.

Single Format: If you selected only one output format, the single audio file will be downloaded directly.

Note: The Save As dialog requires a Chromium-based browser (Chrome, Edge, Brave). Other browsers will download to your default folder.

---

Converting Multiple Files (Queue)

For batch conversion:

1. Select a file and configure options.

2. Click "Add to Queue" instead of "Convert Now".

3. Repeat for more files.

4. Click "Start Queue" to convert all files in order.

5. Download each converted file when ready.

---

Features

• Batch Processing: Convert single files or entire directories (recursive optional).

• Ringtone Mode: Auto-trim to 30s with mobile-friendly defaults.

• Denoising: Built-in spectral gating noise reduction using STFT.

• Format-Specific Optimizations: AMR narrowband telephony settings, etc.

• Audio Effects: Bitrate, sample rate, channel control, fade-in/fade-out, dynamic normalization.

• Metadata Management: Strip metadata for privacy, set title/artist from filename or explicitly.

• Progress Tracking: Visual progress bar with tqdm for batch operations.

• Dry-Run Mode: Preview what would be converted without actually converting.

• Video to MP3: Extract audio from video files.

• Parallel Processing: Multi-worker support for large batches.

• Verbose Logging: Detailed output when you need to debug.

• Graceful Shutdown: Handle Ctrl+C interrupt cleanly.

---

Requirements

Python 3.8+
ffmpeg installed and available in PATH
Python packages (see requirements.txt):
  - numpy>=1.24
  - scipy>=1.10
  - soundfile>=0.12
  - tqdm>=4.65
  - eyeD3>=0.8

Install ffmpeg

Linux

Ubuntu, Debian:

sudo apt install ffmpeg

Arch:

sudo pacman -S ffmpeg

macOS

brew install ffmpeg

Windows

Download from:

https://ffmpeg.org/download.html

Verify ffmpeg installation:

ffmpeg -version

---

Installation

1. Clone the repository:

git clone https://github.com/HelixCipher/myjam.git
cd myjam

2. Install dependencies:

pip install -r requirements.txt

3. Run:

python myjam.py input.wav -t mp3

Or make executable on Linux/macOS:

chmod +x myjam.py
./myjam.py input.wav -t mp3

---

Basic Usage

Convert a single file:

python myjam.py input.wav -t mp3

Convert to multiple formats:

python myjam.py input.wav -t mp3,ogg,aac

Convert all files in a folder:

python myjam.py ./songs -t mp3 -o ./converted

Recursive conversion:

python myjam.py ./songs -t mp3 --recursive

---

Video to MP3 Conversion

Extract audio from video files directly to MP3 format.

python myjam.py video.mp4 --video-to-mp3

Convert all videos in a directory:

python myjam.py ./videos --video-to-mp3 --recursive

With custom bitrate:

python myjam.py movie.mkv --video-to-mp3 -b 192k

Supported Video Formats

• MP4, AVI, MOV, MKV, WebM
• FLV, WMV, M4V, 3GP
• OGV, TS, MPEG, MPG, F4V, VOB

---

Ringtone Mode

Automatically trims to 30 seconds with mobile-friendly defaults.

python myjam.py song.mp3 --ringtone -t mp3

Ringtone defaults:

• 30 seconds duration
• 128k bitrate (for mp3/aac)
• 44.1kHz sample rate

Override if needed:

python myjam.py song.mp3 --ringtone --duration 20 --bitrate 192k

---

Trimming & Effects

Trim audio:

python myjam.py input.wav --start 10 --duration 20

Add fade-in and fade-out:

python myjam.py input.wav --fade-in 2 --fade-out 3

Apply normalization:

python myjam.py input.wav --normalize

---

Advanced Options

Set bitrate:

-b 192k

Set sample rate:

--samplerate 44100

Set channels:

--channels 1

Overwrite existing files:

--overwrite

List supported formats:

--list-formats

---

Dry-Run Mode

Preview what would be converted without actually converting:

python myjam.py ./songs -t mp3 --dry-run

Verbose Logging

Enable detailed output for debugging:

python myjam.py input.wav -t mp3 --verbose

Progress Bar

Visual progress tracking for batch operations:

python myjam.py ./library -t mp3 -o ./converted
# Shows: Converting: 45%|███████████████ | 45/100 [00:30<00:36, 1.52file/s]

Input Validation

Validation with helpful error messages:

python myjam.py input.wav -t mp3 --duration -5
# ERROR: --duration must be positive

---

Strip all metadata and set title from filename:

Removes ALL metadata including embedded images (album art/cover art).

python myjam.py ./songs -t mp3 --strip-metadata --title-from-filename --artist-from-filename -o ./out --recursive

Note: Requires eyeD3 for MP3 files (automatically removes embedded images) and optionally mat2 for other formats. Install with:

pip install eyeD3
pip install mat2  # optional, for non-MP3 formats

Explicitly set metadata title/artist (overrides filename-based tags):

python myjam.py song.wav -t m4a --strip-metadata --title "My Ringtone" --artist "Me" -o out/

---

Denoise a file before conversion

Uses Python STFT-based spectral gating:

python myjam.py noisy_recording.mp3 -t mp3 --denoise --denoise-noise-seconds 0.6 --denoise-thresh 1.5 -o cleaned/

Denoise options:

• --denoise-noise-seconds: Seconds from start to use as noise sample (default: 0.5).

• --denoise-thresh: Threshold multiplier (higher = less aggressive, default: 1.5).

• --denoise-prop-decrease: Noise reduction strength (0-1, default: 1.0 = aggressive).

---

Batch convert large folders in parallel

python myjam.py ./library -t mp3 --strip-metadata --title-from-filename --denoise --workers 4 -o ./ringtones --recursive

---

Format Reference

Format	Codec Used	Notes
MP3	libmp3lame	Widely compatible
WAV	pcm_s16le	Lossless
OGG	libvorbis	Open format
AAC	aac	Useful for streaming
M4A	aac	Apple ecosystem
FLAC	flac	Lossless
OPUS	libopus	Useful compression
AMR	libopencore_amrnb	Telephony (8 kHz, mono default)
QCP	system-dependent	Qualcomm format — support varies by ffmpeg build

---

Important Notes

• Some codecs (AMR, QCP) depend on how your 'ffmpeg' was compiled.

• If conversion fails for a specific format, verify codec availability:

ffmpeg -codecs

• QCP support is limited and may not be available in all builds.

---

Design Philosophy

My Jam leverages the power of ffmpeg for encoding/decoding while adding Python-powered features:

• ffmpeg does the heavy lifting: All encoding/decoding complexity is handled by the proven ffmpeg framework.

• Python adds: Batch processing, denoising, metadata management, validation, and UX improvements.

• User experience matters: Progress bars, dry-run mode, validation, and helpful error messages.

• Privacy: Easy metadata stripping for privacy-conscious users.

---

Why Use My Jam?

My Jam:

• Encapsulates common conversion patterns.

• Applies smart ringtone defaults.

• Simplifies batch processing with progress bars.

• Provides built-in denoising.

• Validates inputs before processing.

• Offers dry-run mode for safety.

• User-friendly interface: No command-line experience required.

• Easy setup: Run with a single Docker command.

---

Command Reference

usage: myjam [-h] [-o OUTDIR] [-t TARGETS] [-b BITRATE]
             [--samplerate SAMPLERATE] [--channels {1,2}] [--start START]
             [--duration DURATION] [--fade-in FADE_IN] [--fade-out FADE_OUT]
             [--ringtone] [--normalize] [--overwrite] [--recursive]
             [--list-formats] [--video-to-mp3] [--strip-metadata]
             [--title-from-filename] [--artist-from-filename] [--title TITLE]
             [--artist ARTIST] [--denoise] [--denoise-noise-seconds DENOISE_NOISE_SECONDS]
             [--denoise-thresh DENOISE_THRESH]
             [--denoise-prop-decrease DENOISE_PROP_DECREASE]
             [--workers WORKERS] [--dry-run] [--verbose]
             input

positional arguments:
  input                 Input file or directory containing audio files

options:
  -h, --help            Show help message and exit
  -o OUTDIR, --outdir OUTDIR
                        Output directory (default: ./converted)
  -t TARGETS, --targets TARGETS
                        Comma-separated target formats (default: mp3)
  -b BITRATE, --bitrate BITRATE
                        Desired audio bitrate (e.g. 128k, 64k)
  --samplerate SAMPLERATE
                        Sample rate in Hz (e.g. 44100)
  --channels {1,2}      Number of audio channels
  --start START         Start time (seconds) to trim from
  --duration DURATION   Duration (seconds) to keep
  --fade-in FADE_IN     Fade-in duration (seconds)
  --fade-out FADE_OUT   Fade-out duration (seconds)
  --ringtone            Use ringtone defaults (30s, 128k, 44100Hz)
  --normalize           Apply dynamic normalization
  --overwrite           Overwrite existing files
  --recursive           Search recursively in directories
  --list-formats        Print supported target formats and exit
  --video-to-mp3        Extract audio from video files to MP3
  --strip-metadata      Strip ALL metadata including embedded images (privacy)
  --title-from-filename Set title tag from filename
  --artist-from-filename
                        Set artist tag from filename
  --title TITLE         Explicit title tag
  --artist ARTIST       Explicit artist tag
  --denoise             Apply spectral-gating denoising
  --denoise-noise-seconds DENOISE_NOISE_SECONDS
                        Seconds for noise sample (default: 0.5)
  --denoise-thresh DENOISE_THRESH
                        Threshold multiplier (default: 1.5)
  --denoise-prop-decrease DENOISE_PROP_DECREASE
                        Noise reduction strength (default: 1.0)
  --workers WORKERS     Number of parallel workers
  --dry-run             Show what would be done without converting
  --verbose, -v         Enable verbose logging

---

Acknowledgement & Attribution

FFmpeg

This project relies on the open-source multimedia framework FFmpeg for all encoding and decoding operations.

FFmpeg is developed and maintained by the global FFmpeg community and provides the core audio processing capabilities used by My Jam.

• Project: https://ffmpeg.org/
• License: LGPL 2.1+ or GPL 2+ (depending on build configuration)
• Copyright © FFmpeg developers

My Jam does not reimplement encoding logic. Instead, it acts as a wrapper around FFmpeg to simplify (CLI and GUI):

• Format conversion

• Metadata stripping and tagging

• Stream mapping

• Audio trimming and filtering

• Codec management

• Batch processing with progress tracking

If you redistribute My Jam together with FFmpeg binaries, ensure you comply with the applicable FFmpeg license (LGPL or GPL depending on your build).

---

License & Attribution

This project is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.

You are free to use, share, copy, modify, and redistribute this material for any purpose (including commercial use), provided that proper attribution is given.

Attribution requirements

Any reuse, redistribution, or derivative work must include:

1. The creator’s name: HelixCipher
2. A link to the original repository:
   https://github.com/HelixCipher/myjam
3. An indication of whether changes were made
4. A reference to the license (CC BY 4.0)

Example Attribution

This work is based on My Jam by HelixCipher.
Original source: https://github.com/HelixCipher/myjam Licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0).

You may place this attribution in a README, documentation, credits section, or other visible location appropriate to the medium.

Full license text: https://creativecommons.org/licenses/by/4.0/

---

Disclaimer

This project is provided “as—is”. The author accepts no responsibility for how this material is used. There is no warranty or guarantee that the scripts are safe, secure, or appropriate for any particular purpose. Use at your own risk.

see DISCLAIMER.md for full terms. Use at your own risk.