🎵 EzPlayer

A lightweight, beautiful audio waveform player for macOS with A-B loop functionality.

Built with SwiftUI • Monokai Pro Theme • Raycast Integration

✨ Features

• Waveform Visualization - Real-time audio waveform display with playback progress
• A-B Loop Playback - Set start (S) and end (E) points for seamless loop practice
• Variable Speed - Playback speed control from 0.3x to 1.5x with preset buttons
• Settings Persistence - Loop markers, speed, volume and position are remembered per file
• Raycast Integration - Quick launch from Finder via Raycast script
• Video Support - Auto-converts MP4/MOV/MKV to audio for playback
• Monokai Pro Theme - Beautiful dark interface with carefully chosen colors
• Keyboard Shortcuts - Full keyboard control for efficient workflow

📋 Requirements

• macOS 12.0 (Monterey) or later
• Xcode Command Line Tools (for building)
• Raycast (optional, for Finder integration)
• FFmpeg (optional, for video-to-audio conversion)

🚀 Installation

Build & Install

git clone https://github.com/yourusername/EzPlayer.git
cd EzPlayer
./build.sh

The build script compiles the source, bundles the app icon, and installs to /Applications/EzPlayer.app automatically.

🔗 Raycast Setup

EzPlayer includes a Raycast script for quick access. Select an audio/video file in Finder and trigger EzPlayer instantly!

Setup Steps

1. Open Raycast Preferences → Extensions → Script Commands

2. Add Script Directory

   • Click "Add Directories"
   • Select EzPlayer/Scripts/ folder

3. Configure the script (if needed)

   Edit Scripts/ezplayer.sh and update the APP_PATH variable:

   APP_PATH="/Applications/EzPlayer.app"

4. Grant permissions

   • On first run, grant Finder automation permission when prompted

Usage

1. Select an audio or video file in Finder
2. Open Raycast (default: ⌘ + Space)
3. Type "EzPlayer" and press Enter
4. The file opens in EzPlayer! 🎉

Tip: For video files (MP4, MOV, MKV), the script will auto-convert to WAV using FFmpeg.

⌨️ Keyboard Shortcuts

Shortcut	Action
Space	Play / Pause
Space × 2	Jump to loop start (or beginning)
← / →	Seek backward / forward 2s
⌘ ⇧ S	Set loop Start point
⌘ ⇧ E	Set loop End point
⌘ ⇧ C	Clear all loop markers
⌘ /	Show keyboard shortcuts
⌘ ⇧ ?	Show documentation
⌘ W	Close window
⌘ Q	Quit application

🔁 Loop Playback Guide

EzPlayer's A-B loop feature is perfect for practicing music, transcribing audio, or studying specific sections:

1. During playback, press ⌘ ⇧ S to mark the current position as Start (red "S" marker)
2. Keep listening, then press ⌘ ⇧ E to mark End (blue "E" marker)
3. Playback will automatically loop between Start and End

You can also click on the waveform to seek to a position before setting markers.

The loop region is highlighted in yellow/orange on the waveform. Press ⌘ ⇧ C to clear all markers.

Note: If you set End before Start, the position becomes the new Start point instead.

💾 Settings Persistence

EzPlayer automatically remembers settings for each audio file you open:

• Loop start / end markers
• Playback speed and volume
• Last playback position

Settings are stored in ~/Library/Application Support/EzPlayer/cache/ and expire after 30 days.

🎵 Supported Formats

Audio (Direct Playback)

• MP3, M4A, AAC
• WAV, AIFF
• FLAC (if system codec available)

Video (Auto-converted to WAV)

• MP4, M4V, MOV
• MKV, WebM

Video conversion requires FFmpeg. Install with: brew install ffmpeg

📄 License

MIT License - feel free to use and modify as you wish.

---

Made with ❤️ for all Transcribers