AI-Assisted Development: This tool was developed with substantial assistance from Artificial Intelligence (AI), specifically Large Language Models (LLMs). AI played a significant role in:
- Generating initial code structures and function implementations based on requirements.
- Refactoring code for better organization, error handling, and platform compatibility (POSIX/Windows).
- Implementing complex algorithms like Continued Fraction Expansion (CFE) and safe arithmetic checks.
- Debugging logical errors, identifying edge cases (like the interaction between search modes and priorities), and suggesting fixes.
- Generating platform-specific code (e.g., Windows `WaitForMultipleObjects` vs. POSIX signal handling).
- Explaining concepts and clarifying algorithm behavior.
- Writing documentation and generating this HTML page.
Human oversight directed the process, defined the specifications, reviewed the code, performed testing, and made final decisions, but the AI contribution was integral to the speed and scope of development. While efforts were made to ensure quality, the significant reliance on AI means the resulting codebase might exhibit some inconsistencies, areas needing optimization, or contain undiscovered bugs.
Overview
This command-line tool calculates suitable integer Interpolation (L
) and Decimation (M
) factors for rational resampling tasks, commonly encountered in digital audio and signal processing. When changing sample rates between two frequencies that do not share a simple integer relationship (e.g., 44.1 kHz to 48 kHz), a rational resampler using L/M factors is often employed.
The tool utilizes Continued Fraction Expansion (CFE) to find the best rational approximations of the target resampling ratio (Output Rate / Input Rate) and integer factorization to explore single-stage and two-stage resampling options.
Core Features
- Calculates L/M factors for single-stage rational resampling.
- Calculates L1/M1 and L2/M2 factor pairs for two-stage rational resampling.
- Provides two search modes for two-stage resampling:
- Minimal Sum: Finds the solution with the mathematically lowest sum L1+M1+L2+M2, often leading to simpler implementations (within internal limits).
- Custom Limit: Allows specifying a maximum value per L/M factor, searching for the most accurate result within that complexity constraint.
- Supports targeting an optional intermediate sample rate in two-stage mode.
- Offers different prioritization strategies when targeting an intermediate rate (Strict, Final Rate, Balanced Dual, Best Overall).
- Includes constraint options (e.g., allowing/disallowing M1 > L1).
- Provides detailed results including achieved rates, absolute/relative errors, and PPM error.
- Issues warnings for potentially problematic results (e.g., large L/M factors, significant approximation errors).
- Handles user interrupts (Ctrl+C) gracefully across POSIX and Windows.
Building the Tool (CMake)
This project uses CMake for building. Ensure you have CMake and a C compiler (like GCC, Clang, or MSVC) installed. The tool only depends on the standard C library; no external libraries are required.
- Navigate to the root directory of the project in your terminal.
- Create a build directory:
mkdir build
- Change into the build directory:
cd build
- Run CMake to configure the project (use
cmake .. -G "Your Generator"
if needed, e.g., for Visual Studio):cmake ..
- Build the project (the
-j 4
suggests using 4 parallel jobs, adjust as needed):make -j 4
(Or use the appropriate build command for your generator, e.g.,
cmake --build .
) - (Optional) Install the executable to the location specified in CMakeLists.txt (often
/usr/local/bin
or similar):sudo make install
(Requires appropriate permissions).
After building or downloading, the executable (e.g., LM_Calc.exe
or LM_Calc
) will be located in the build directory (or the installation path).
Windows Users: This is a command-line application. You must run it from a terminal like Command Prompt (cmd.exe
), PowerShell, or Windows Terminal. Do not simply double-click the .exe
file, as it needs the console window to interact with you. Navigate to the directory containing the executable in your chosen terminal before running it.
Usage Examples
Example 1: Single-Stage Resampler (44.1 kHz to 96 kHz)
Run the executable from your terminal:
$ ./LM_Calc
=== Rational Resampler L/M Calculator ===
Calculates Interpolation (L) and Decimation (M) values.
Uses Continued Fraction Expansion (CFE) and Factorization.
=====================================================
Enter the input sample rate (Hz): 44100
Enter the output sample rate (Hz): 96000
Use one or two rational resamplers? (1 or 2): 1
--- Single Rational Resampler Calculation ---
Target: Input Rate = 44100.00 Hz, Output Rate = 96000.00 Hz
Target Ratio (output/input) = 2.1768707483
Match Tolerance (relative error): 1.0e-09
Arbitrary Suggestion Threshold (relative error): 1.0e-06
CFE searching with max denominator M <= 65535
Results: Match Found!
L = 320 (Interpolation)
M = 147 (Decimation)
Complexity = 320
Achieved Ratio (L/M) = 320 / 147 = 2.1768707483
Achieved Output Rate = 96000.0000000000 Hz
Rate Difference: +0.0000000000 Hz, Relative: 0.00e+00
PPM Error: +0.000 PPM
Perform another sample rate conversion? (y/n) [Enter=n]: n
Exiting program normally.
Example 2: Two-Stage Resampler (44.1 kHz to 32 kHz)
This example converts CD audio rate to DAT rate. While a single stage (L=320, M=441) can achieve this exact ratio, using two stages often results in factors with lower overall complexity, potentially leading to more efficient filter implementations. This example uses the Minimal Sum mode. Note that we allow M1 > L1 ('y') to enable potentially better factorizations.
$ ./LM_Calc
=== Rational Resampler L/M Calculator ===
Calculates Interpolation (L) and Decimation (M) values.
Uses Continued Fraction Expansion (CFE) and Factorization.
=====================================================
Enter the input sample rate (Hz): 44100
Enter the output sample rate (Hz): 32000
Use one or two rational resamplers? (1 or 2): 2
Two-Resampler Search Mode:
1: Default Minimal Sum (Find match/approximation with smallest L1+M1+L2+M2 sum)
2: Custom Limit Search (Search using custom max L/M values you provide)
Select search mode (1 or 2) [Enter=1]:
-> Minimal Sum mode selected (default).
Note: Minimal Sum mode selected. Using internal max L/M limit: 65535.
and explores solutions for the lowest L+M sum.
Constraint: By default, the first stage ensures L1 >= M1.
Allow the first stage to downsample (M1 > L1)?
(Useful for intermediate processing at lower rates, but may seem
less direct for pure sample rate conversion.)
Allow M1 > L1? (y/n) [Enter=n]: y
-> M1 > L1 Allowed.
Optional: Specify a target intermediate sample rate.
If skipped (by pressing Enter), the search will not target
a specific intermediate rate.
Enter target intermediate rate (Hz) (rate after L1/M1) [Press Enter to skip]:
-> Skipped intermediate rate target.
--- Two Rational Resampler Calculation (Minimal Sum Mode) ---
Max L/M per stage: 65535
Constraint: M1 > L1 is Allowed
Target: Input Rate = 44100.00 Hz, Output Rate = 32000.00 Hz
Target Ratio (output/input) = 0.7256235828
Match Tolerance (relative error): Overall=1.0e-09, Intermediate=1.0e-09
Arbitrary Suggestion Threshold (relative error): 1.0e-06
CFE searching with max overall denominator Q <= 4294836225
Starting search calculation. Please wait...
Progress (checking CFE convergents): .
1 CFE convergents processed...
Checked factor pairs and possibly common factors (g/h)...
Done searching!
Minimal Sum Search Results: Match Found!
First Resampler: Complexity: 147
L1 = 64 (Interpolation)
M1 = 147 (Decimation)
Second Resampler: Complexity: 5
L2 = 5 (Interpolation)
M2 = 3 (Decimation)
Overall Sum (L1+M1+L2+M2) = 219
Overall Complexity (Sum of Max) = 152
Achieved Combined Ratio = (64 / 147) * (5 / 3) = 0.7256235828
Achieved Intermediate Rate = 19200.0000000000 Hz
Achieved Output Rate = 32000.0000000000 Hz
Overall Rate Difference: +0.0000000000 Hz, Relative: 0.00e+00
Overall PPM Error: +0.000 PPM
Perform another sample rate conversion? (y/n) [Enter=n]: n
Exiting program normally.
Example 3: Advanced Two-Stage (48 kHz to 99 kHz, Custom Limit, Intermediate Target)
This demonstrates using the Custom Limit search mode, specifying a maximum L/M per stage, targeting an intermediate rate, and using the Balanced Dual priority.
$ ./LM_Calc
=== Rational Resampler L/M Calculator ===
Calculates Interpolation (L) and Decimation (M) values.
Uses Continued Fraction Expansion (CFE) and Factorization.
=====================================================
Enter the input sample rate (Hz): 48000
Enter the output sample rate (Hz): 99000
Use one or two rational resamplers? (1 or 2): 2
Two-Resampler Search Mode:
1: Default Minimal Sum (Find match/approximation with smallest L1+M1+L2+M2 sum)
2: Custom Limit Search (Search using custom max L/M values you provide)
Select search mode (1 or 2) [Enter=1]: 2
-> Custom Limit Search mode selected.
Enter maximum L and M for EACH stage (e.g., 200): 100
Constraint: By default, the first stage ensures L1 >= M1.
Allow the first stage to downsample (M1 > L1)?
(Useful for intermediate processing at lower rates, but may seem
less direct for pure sample rate conversion.)
Allow M1 > L1? (y/n) [Enter=n]:
Optional: Specify a target intermediate sample rate.
If skipped (by pressing Enter), the search will not target
a specific intermediate rate.
Enter target intermediate rate (Hz) (rate after L1/M1) [Press Enter to skip]: 72000
-> Targeting intermediate rate: 72000.00 Hz
Intermediate Rate Prioritization:
How should the search prioritize finding this rate versus the final output rate?
1: Strictly Enforce Intermediate Rate:
Only solutions matching the intermediate target (within 1.0e-09 relative error)
will be considered. The best of these is chosen based on the search mode
(Minimal Sum or best overall accuracy).
2: Prioritize Final Output Rate:
Solutions matching the final target (within 1.0e-09 relative error) are preferred.
Among those, the one closest to the intermediate target is chosen.
If no final match exists, the overall best approximation (by search mode) is chosen.
3: Balanced - Best Dual Match (if possible):
Solutions matching *both* targets are preferred. Among those, the best by
search mode is chosen. If no dual match exists, falls back to
PRIORITIZE_FINAL_RATE logic.
4: Ignore Intermediate Rate for Selection:
The intermediate target is ignored during selection. The best solution
is chosen based *only* on the final rate accuracy and the primary search mode.
The achieved intermediate rate is still reported.
Select prioritization mode (1-4): 3
--- Two Rational Resampler Calculation (Custom Limit Mode) ---
Max L/M per stage: 100
Target Intermediate Rate: 72000.00 Hz (Priority: Balanced Dual)
Constraint: M1 > L1 is NOT Allowed
Target: Input Rate = 48000.00 Hz, Output Rate = 99000.00 Hz
Target Ratio (output/input) = 2.0625000000
Match Tolerance (relative error): Overall=1.0e-09, Intermediate=1.0e-09
Arbitrary Suggestion Threshold (relative error): 1.0e-06
CFE searching with max overall denominator Q <= 10000
Starting search calculation. Please wait...
1 CFE convergents processed...
Checked factor pairs...
Done searching!
Custom Limit Search Results: Match Found!
First Resampler: Complexity: 3
L1 = 3 (Interpolation)
M1 = 2 (Decimation)
Second Resampler: Complexity: 11
L2 = 11 (Interpolation)
M2 = 8 (Decimation)
Overall Sum (L1+M1+L2+M2) = 24
Overall Complexity (Sum of Max) = 14
Achieved Combined Ratio = (3 / 2) * (11 / 8) = 2.0625000000
Achieved Intermediate Rate = 72000.0000000000 Hz
Achieved Output Rate = 99000.0000000000 Hz
Overall Rate Difference: +0.0000000000 Hz, Relative: 0.00e+00
Overall PPM Error: +0.000 PPM
Intermediate Rate Difference: +0.0000000000 Hz, Relative: 0.00e+00
Intermediate PPM Error: +0.000 PPM
Perform another sample rate conversion? (y/n) [Enter=n]: n
Exiting program normally.
Disclaimer of Warranty & Limitation of Liability
This software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.
You use this software entirely at your own risk.
Downloads
Get the pre-compiled Windows executable or the source code to build it yourself.
Alternatively: For quick calculations or if you prefer not to download/install software, you can also use the web-based version of this tool: Here
Download Windows Binary 64-bit (.exe) Download Source Code (.zip)Windows Binary Requirements & Notes:
- Operating System: Windows 8 64-bit or newer
Note: The Windows binary is provided for convenience. Building from source is recommended for other platforms (Linux, macOS) or for modifications.