Our Story

Vinylfy started as a project for my daughter, who is a big fan of vinyl records. Due to her limited budget, she asked if there was a way to make her collection of MP3s sound more like her preferred sound. Hence, Vinylfy was born.

Vinylfy's "AJW Recommended" preset is tuned for her favorite sound, and it is a great starting point for anyone looking to get started with Vinylfy. It is the default preset for Vinylfy, and it is based on her favorite records.

Documentation

Welcome to the Vinylfy documentation. Here you will find everything you need to know about setting up, deploying, and customizing your own instance of Vinylfy.

Quick Start

Vinylfy is a web application that can be run on any local server via Docker. The easiet way to get started is to use Docker Compose with a environment variables.

You can deploy Vinylfy with default settings through either Docker Hub or GHCR.

Via Docker Hub:

docker run -d -p 8888:8888 --name vinylfy 121gigawatz/vinylfy:latest
                

Via GHCR:

docker run -d -p 8888:8888 --name vinylfy ghcr.io/121gigawatz/vinylfy:latest
                

Environment Variables

Vinylfy uses environment variables to configure the application. Below is a table of the environment variables that are used by Vinylfy.

First, create a .env file in the root directory of the project.

# Vinylfy Environment Configuration
# Copy this file to .env and customize for your environment

# ============================================================================
# APPLICATION SETTINGS
# ============================================================================

# Flask environment (development, production)
FLASK_ENV=production

# Enable debug mode (true/false) - DO NOT use in production
DEBUG_MODE=false

# Secret key for session management - CHANGE THIS IN PRODUCTION!
SECRET_KEY=change-me-in-production-use-a-long-random-string

# ============================================================================
# SERVER SETTINGS
# ============================================================================

# Port to expose the application (default: 8888)
PORT=8888

# ============================================================================
# FILE UPLOAD SETTINGS
# ============================================================================

# Maximum upload file size in MB (default: 25)
MAX_UPLOAD_SIZE=25

# File time-to-live in hours before automatic deletion (default: 1)
# Supports decimals (e.g. 0.5 for 30 minutes)
FILE_TTL_HOURS=1

# ============================================================================
# CORS SETTINGS
# ============================================================================

# Allowed CORS origins
# Controls which domains can access the API.
# Use '*' to allow ALL domains (easiest).
# For production, list specific domains to improve security. 
# If using a reverse proxy, include the FQDN or IP the *browser* uses.
# IMPORTANT: Origins must be `protocol://domain:port` (NO trailing slash or path!).
# (e.g., https://yourdomain.com NOT https://yourdomain.com/api/)

#
# Examples:
#   CORS_ORIGINS=*
#   CORS_ORIGINS=https://yourdomain.com,http://localhost:5500,http://192.160.1.1:5500
#
CORS_ORIGINS=*

# ============================================================================
# DOCKER RESOURCE LIMITS (Optional)
# ============================================================================

# CPU limit (default: 2.0 cores)
# DOCKER_CPU_LIMIT=2.0

# Memory limit (default: 1G)
# DOCKER_MEMORY_LIMIT=1G

# ============================================================================
# NOTES
# ============================================================================

# - All settings have sensible defaults
# - Only SECRET_KEY must be changed for production
# - Files are automatically cleaned up after FILE_TTL_HOURS
# - Persistent data is stored in Docker volume 'vinylfy-data'

                

Next, create a docker-compose.yml file in the root directory of the project.

version: '3.8'

services:
    vinylfy:
        image: 121gigawatz/vinylfy:latest
        env_file: .env
        volumes:
            - ./data:/app/data
                

Installation

Navigate to the directory where your dokcer-compose.yml and .env file is stored. Open up a terminal and run the following:

docker compose up -d
                

This will start the Vinylfy application in a Docker container. Note the "-d" flag is optional and will deploy the container in the background. If you omit the "-d" flag, the container will start in the foreground and you will see the logs in real-time.

Security

Vinylfy does not require a login or password to access the application. If exposing this to the internet, we recommend using either reverse proxy, secure VPN tunnel, or SSO provider to secure access to the application.

Some good options for SSO providers include:

• Authentik
• Authelia
• Keycloak

Reverse Proxy Setup

Vinylfy can be deployed behind a reverse proxy to improve security and performance. We recommend using a reverse proxy to secure access to the application.

Some good options for reverse proxies include:

• Caddy
• Nginx Proxy Manager
• Traefik

Please ensure your reverse proxy is configured to forward the correct headers to the application.

Vinylfy includes an nginx.conf file internally for the API. Please do not modify. this file unless you know what you're doing!

Using Vinylfy

Once you have Vinylfy running (either locally or deployed), open your browser and navigate to the application URL (e.g., http://localhost:8888 or https://vinylfy.yourdomain.com).

Vinylfy will launch immmediately in your browser. If you are accessing Vinylfy on a mobile device for the first time, you will be prompted to install Vinylfy as a Progressive Web App (PWA), if your browser, device, and operating system support it. See more information about PWA in Vinylfy below.

1. Load An Audio File

Click the "Select File" area or drag and drop an audio file onto the drop zone. Supported formats include MP3, WAV, FLAC, AAC, and OGG.

2. Select a Preset

Vinylfy comes with era-specific presets that instantly tune the audio characteristics. Choose from "1920s Jazz", "1970s Rock", "Modern Vinyl", and more. The default "AJW Recommended" preset offers a balanced, high-quality analog warmth.

Click the "Presets" tab to view all available presets. You can also choose our Custom Preset to fine-tune the audio characteristics to your liking. If you change the settings on the next tab, the Custom Preset will be applied automatically.

3. Configure Output

For advanced control, click the "Configure" tab. Here you can tweak individual parameters:

There are three main sections in the Configure tab:

• Vinyl Effects: This section is designed to simulate the physicl effects of vinyl records, such as Noise Intensity (surface noise and mechanical noise), Pop Intensity (pops/crackles), Wow & Flutter (subtle pitch variations and speed variations), and Distortion Amount (analog warmth).
• Equalizer: Fine tune the EQ curves (bass, mids, and trebles) to your liking.
• Filters: Deeper control over the sound, including a low-pass filter and a high-pass filter to remove unwanted frequencies. Apply the RIAA equalization curve to simulate the sound of vinyl records.

Each preset is a unique combination of applying the vinyl effects, equalizer, and filters. Below is a table of all of the presets and their settings.

4. Process Your File

When you are happy with your settings, click the large "Process" button. This sends your file to the backend where the effects are applied. Processing time depends on the file length.

5. Preview Results

Once processing is complete, you will be automatically be redirected to the Results tab. In this tab, you will see three sections: Audio Player, Processing Details, Track Metadata, and Download.

The Audio Player allows you to listen to the processed file through your browser.

The Processing Details section shows you the settings that were applied to the file.

6. Manage Metadata

If the uploaded file has metadata already embedded, it will be displayed in the metadata area. If you wish to change any metadata, or if no metadata exists, click the Edit button to update the track metadata. Use the metadata editor to update the Track Title, Artist, Album, Year, Genre, and any Comments. You can also upload custom Cover Art which will be embedded into the final file. By default, the comments field will include "Processed with Vinylfy using the [Preset Name] preset". However, you can remove this comment if you wish, and/or add your own custom comment.

When finished, click the "Save" button to save your metadata. Note that the metadata will not be saved until you click the "Save" button. The metadata will be embedded into the file upon download.

7. Export / Download Your File

Finally, you can download your processed file in your preferred format. You can download the individual processed track in a specific format, or a ZIP file containing multiple formats if needed.

In this section, you can select the format you would like to download. Each format shows an estimated size of the downloaded file.

If you would like to change your settings, click the "Change Settings" button. If you have another track to process, or would like to start over, click the "Discard & Start Over" button.

FAQ