===============================================================================
                    ZAP AUDIO CODEC v1.0.0
                         README (ENGLISH)
===============================================================================

WELCOME TO ZAP!
---------------
ZAP (Zero Audible Psychoacoustic) is a cutting-edge audio codec that 
delivers studio-quality sound at low bitrates. Designed for audiophiles, 
producers, and anyone who values lossless quality in a compact format.

===============================================================================
QUICK START
===============================================================================

INSTALLATION
------------
1. Extract the downloaded ZIP file
2. The program is ready to use - no installation required!

SYSTEM REQUIREMENTS
-------------------
- Windows, macOS, or Linux
- At least 2 GB RAM
- Multi-core processor recommended (for faster encoding)
- Audio output device

===============================================================================
BASIC USAGE
===============================================================================

ZAP offers three main functions:

1. ENCODING (ENCODE)
--------------------
Converts lossless audio files to ZAP format.

Syntax:
    zap_codec encode <input_file> [OPTIONS]

Examples:
    zap_codec encode my_song.wav
    zap_codec encode studio_mix.flac
    zap_codec encode album_track.aiff

IMPORTANT: Only lossless formats are accepted!
✓ Supported: WAV, FLAC, AIFF
✗ Not supported: MP3, OGG, AAC, M4A (lossy formats)

2. PLAYBACK (PLAY)
------------------
Plays ZAP files directly.

Syntax:
    zap_codec play <file.zap>

Example:
    zap_codec play my_song.zap

Controls:
    - Press Ctrl+C to stop
    - Progress bar shows current position

3. DECODING (DECODE)
--------------------
Converts ZAP files back to WAV.

Syntax:
    zap_codec decode <file.zap> [output.wav]

Examples:
    zap_codec decode my_song.zap
    zap_codec decode my_song.zap restored.wav

If no output name is specified, the file will be named "decoded.wav"

===============================================================================
ADDING METADATA
===============================================================================

You can add or override metadata during encoding:

AVAILABLE OPTIONS
-----------------
--title "Song Title"         Track title
--artist "Artist Name"       Artist name
--album "Album Name"         Album name
--year "2025"                Release year
--genre "Rock"               Music genre
--track 3                    Track number
--comment "Comment"          Additional comment

EXAMPLE WITH METADATA
---------------------
zap_codec encode song.wav --title "Midnight Dreams" --artist "The Band" 
          --album "Greatest Hits" --year "2025" --genre "Jazz" --track 5

NOTE: If your input file already contains metadata (e.g., in FLAC or MP3 
tags), it will be automatically extracted. Use the above options to 
override them.

===============================================================================
WORKFLOW EXAMPLES
===============================================================================

SCENARIO 1: ENCODE A SINGLE FILE
---------------------------------
1. Open a terminal/command prompt
2. Navigate to the ZAP folder
3. Run:
   
   zap_codec encode my_music.flac

4. Done! The file "my_music.zap" has been created

SCENARIO 2: ENCODE WITH METADATA
---------------------------------
zap_codec encode track.wav --title "Summer Rain" --artist "John Doe"

SCENARIO 3: LISTEN THEN DECODE
-------------------------------
1. First, listen:
   zap_codec play song.zap

2. Like it? Then decode:
   zap_codec decode song.zap original.wav

SCENARIO 4: PROCESS ENTIRE ALBUM
---------------------------------
For multiple files, you can create a batch file/shell script:

Windows (batch.bat):
    @echo off
    for %%f in (*.flac) do zap_codec encode "%%f"

Linux/Mac (batch.sh):
    #!/bin/bash
    for file in *.flac; do
        zap_codec encode "$file"
    done

===============================================================================
TECHNICAL DETAILS
===============================================================================

WHAT MAKES ZAP SPECIAL?
------------------------
✓ Psychoacoustic Encoding - Leverages human hearing characteristics
✓ Smart Mid/Side Stereo - Automatic optimization
✓ Transparent Dynamics Processing - Subtle enhancement without artifacts
✓ 64-bit Processing - Highest precision
✓ Multi-core Support - Fast encoding on modern CPUs

QUALITY
-------
- Target Bitrate: < 280 kbps
- Compression: 70-85% size reduction
- Fidelity: 93-99% (transparent quality)
- Frequency Range: 10 Hz - 22 kHz

SUPPORTED FORMATS
-----------------
Input (Encoding):
    - WAV (Waveform Audio File Format)
    - FLAC (Free Lossless Audio Codec)
    - AIFF (Audio Interchange File Format)

Output (Decoding):
    - WAV (16-bit PCM)

===============================================================================
FREQUENTLY ASKED QUESTIONS (FAQ)
===============================================================================

Q: Why isn't my MP3 file accepted?
A: ZAP is optimized for lossless sources. MP3 is already compressed and
   would lead to quality loss. Use WAV, FLAC, or AIFF instead.

Q: How long does encoding take?
A: Depends on file length and CPU performance. A 3-minute file typically
   takes 10-30 seconds on modern systems.

Q: Is the quality truly lossless?
A: ZAP is a "transparent" lossy codec - optimized for inaudible losses.
   For absolute bit-perfect accuracy, continue using FLAC.

Q: Can I use ZAP for commercial projects?
A: Yes, but please credit the project. See license for details.

Q: How large will ZAP files be?
A: Typically 15-30% of the original WAV size, depending on the audio
   material (complex music = larger, speech = smaller).

Q: Are cover arts stored?
A: ZAP stores info on WHETHER a cover exists, but not the image itself.
   This will be added in future versions.

Q: Can I change the bitrate?
A: The maximum bitrate is fixed at 280 kbps. For other values, you need
   to modify the source code (see DOCUMENTATION.txt).

===============================================================================
TROUBLESHOOTING
===============================================================================

PROBLEM: "Lossy format detected"
SOLUTION: Your file is already compressed (MP3, OGG, etc.).
          Convert to WAV or FLAC first.

PROBLEM: Playback stutters
SOLUTION: - Close other programs
          - Check CPU usage
          - Use a faster computer

PROBLEM: "File not found"
SOLUTION: - Check the file path
          - Use quotes for spaces: "my song.wav"
          - Navigate to the correct folder

PROBLEM: Metadata not saved
SOLUTION: - Check if input file contains tags
          - Use manual flags (--title, --artist, etc.)

PROBLEM: Output file too large
SOLUTION: ZAP is optimized for studio recordings. Very complex material
          may result in larger files.

===============================================================================
PERFORMANCE TIPS
===============================================================================

FOR FASTER ENCODING
-------------------
✓ Use a multi-core processor (4+ cores)
✓ Close other programs
✓ Use an SSD instead of HDD
✓ Encode multiple files in parallel (separate terminals)

FOR BEST QUALITY
----------------
✓ Use high-quality sources (24-bit/96kHz if available)
✓ Use FLAC as input format
✓ Avoid multiple encoding cycles (WAV→ZAP→WAV→ZAP)

===============================================================================
PROJECT INFORMATION
===============================================================================

VERSION: 1.0.0
RELEASE: 2025
DEVELOPER: Christian Schwarzer
CONTACT: c-schwarzer@web.de
WEBSITE: https://hdspace.eu

LICENSE
-------
Open-source (specific license TBD)

When using or modifying, please credit:
"Powered by ZAP Audio Codec v1.0.0 by Christian Schwarzer"

===============================================================================
FURTHER DOCUMENTATION
===============================================================================

For detailed technical information, see:
- DOCUMENTATION.txt (complete technical specification)
- Source Code (main.rs with detailed comments)

For questions, bugs, or feature requests:
- Email: c-schwarzer@web.de
- Or use the thumbs-down button in the HDSpace interface

===============================================================================
THANK YOU
===============================================================================

Thank you for using ZAP! This project was developed with passion for
high-quality audio compression.

If you like ZAP, tell others about it!

Happy Listening! 🎵

===============================================================================
                              END
===============================================================================