mksinewave 1.0.0__tar.gz

mksinewave-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: mksinewave
+Version: 1.0.0
+Summary: Simple command-line tool for creating audio files containing pure sine wave tones
+Author: DJ Stomp
+Author-email: 85457381+DJStompZone@users.noreply.github.com
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: dev
+Requires-Dist: numpy (>=2.5.3,<3.0.0)
+Requires-Dist: pytest (>=9.1.1,<10.0.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=7.1.0,<8.0.0) ; extra == "dev"
+Requires-Dist: soundfile (>=0.14.0,<0.15.0)
+Description-Content-Type: text/markdown
+
+# mksinewave
+
+`mksinewave` is a Python command-line utility for generating pure sine wave audio tones with customizable configurations, smooth attenuation fades, and automatic audio container inference.
+
+[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/mksinewave)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Flexible Frequency Formats:** Accepts standard numbers (`440`), human-friendly shortcuts (`1.4k'), or explicit units (`22kHz`).
+- **Smart Fades:** Prevent harsh audio pops and clicks with customizable linear head and tail attenuation (fade-in/fade-out).
+- **FFmpeg-Style Extension Inference:** Saves directly to `.wav`, `.flac`, `.ogg`, or `.aiff` by automatically detecting the format from your output filename.
+- **Safety Proofed:** Includes built-in human hearing range guards (20 Hz - 22 kHz) and Nyquist frequency anti-aliasing checks.
+- **Safe Overwriting:** Protects existing files unless exlplicitly overridden with the `-f / --force` flag.
+
+## Installation
+
+Clone the repository and install it locally using `pip`:
+
+```bash
+pip install mksinewave
+```
+
+For active local development, install using the `[dev]` optional dependency group in editable mode:
+
+```bash
+pip install -e "mksinewave[dev]"
+```
+
+## Usage
+
+Once installed, the global `mksinewave` command is available anywhere on your system.
+
+### Basic Syntax
+
+```bash
+mksinewave <frequency> <duration> [options]
+```
+
+### Examples
+
+**1. Generate a standard A4 tone (440Hz) for 3 seconds:**
+
+```bash
+mksinewave 440 3
+```
+
+**2. Generate a 1.5 khz tone for 5 seconds as a compressed FLAC file with a smooth fade-in and fade-out:**
+
+```bash
+mosinewave 1.5k 5 --fade-sin 0.5 --fade-out 1.0 -o output.flac -v
+```
+
+**3. Force overwrite an existing file using a specific sample rate:**
+
+```bash
+mksinewave "2.2 kHz" 2.5 -s 48000 -o alert.ogg -f
+```
+
+### Available Command-Line Flags
+
+- --fade-in: Length of head attenuation fade-in in seconds (Default: 0.0).
+- --fade-out: Length of tail attenuation fade-out in" seconds (Default: 0.0).
+- -s, --sample-rate: Audio sampling rate in Hz (Default: 44100).
+- -o, --output: Output filepath inferred via extension (Default: sine_wave.wav).
+- -f, --force: Overwrite the target file if it already exists.
+- -v, --verbose: Enable logging output detailing the generation process.
+- frequency (Positional): Target frequency. Supports formats like 440, 1.4k, 22kHz.
+- duration (Positional): Total length of the audio track in seconds.
+
+## Development & Testing
+
+This project maintains rigorus test coverage using `pytest` and `pytest-cov`.
+
+If you installed the development dependencies, you can execute the test suite globally from the project root directory:
+
+```bash
+test-mksinewave
+```
+
+## License
+
+This project is licensed under the MIT License.
+See the [LICENSE](LICENSE) file for details.
+

mksinewave-1.0.0/README.md

@@ -0,0 +1,84 @@
+# mksinewave
+
+`mksinewave` is a Python command-line utility for generating pure sine wave audio tones with customizable configurations, smooth attenuation fades, and automatic audio container inference.
+
+[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/mksinewave)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Flexible Frequency Formats:** Accepts standard numbers (`440`), human-friendly shortcuts (`1.4k'), or explicit units (`22kHz`).
+- **Smart Fades:** Prevent harsh audio pops and clicks with customizable linear head and tail attenuation (fade-in/fade-out).
+- **FFmpeg-Style Extension Inference:** Saves directly to `.wav`, `.flac`, `.ogg`, or `.aiff` by automatically detecting the format from your output filename.
+- **Safety Proofed:** Includes built-in human hearing range guards (20 Hz - 22 kHz) and Nyquist frequency anti-aliasing checks.
+- **Safe Overwriting:** Protects existing files unless exlplicitly overridden with the `-f / --force` flag.
+
+## Installation
+
+Clone the repository and install it locally using `pip`:
+
+```bash
+pip install mksinewave
+```
+
+For active local development, install using the `[dev]` optional dependency group in editable mode:
+
+```bash
+pip install -e "mksinewave[dev]"
+```
+
+## Usage
+
+Once installed, the global `mksinewave` command is available anywhere on your system.
+
+### Basic Syntax
+
+```bash
+mksinewave <frequency> <duration> [options]
+```
+
+### Examples
+
+**1. Generate a standard A4 tone (440Hz) for 3 seconds:**
+
+```bash
+mksinewave 440 3
+```
+
+**2. Generate a 1.5 khz tone for 5 seconds as a compressed FLAC file with a smooth fade-in and fade-out:**
+
+```bash
+mosinewave 1.5k 5 --fade-sin 0.5 --fade-out 1.0 -o output.flac -v
+```
+
+**3. Force overwrite an existing file using a specific sample rate:**
+
+```bash
+mksinewave "2.2 kHz" 2.5 -s 48000 -o alert.ogg -f
+```
+
+### Available Command-Line Flags
+
+- --fade-in: Length of head attenuation fade-in in seconds (Default: 0.0).
+- --fade-out: Length of tail attenuation fade-out in" seconds (Default: 0.0).
+- -s, --sample-rate: Audio sampling rate in Hz (Default: 44100).
+- -o, --output: Output filepath inferred via extension (Default: sine_wave.wav).
+- -f, --force: Overwrite the target file if it already exists.
+- -v, --verbose: Enable logging output detailing the generation process.
+- frequency (Positional): Target frequency. Supports formats like 440, 1.4k, 22kHz.
+- duration (Positional): Total length of the audio track in seconds.
+
+## Development & Testing
+
+This project maintains rigorus test coverage using `pytest` and `pytest-cov`.
+
+If you installed the development dependencies, you can execute the test suite globally from the project root directory:
+
+```bash
+test-mksinewave
+```
+
+## License
+
+This project is licensed under the MIT License.
+See the [LICENSE](LICENSE) file for details.

mksinewave-1.0.0/mksinewave/__main__.py

@@ -0,0 +1,4 @@
+from mksinewave.mksinewave import main
+
+if __name__ == "__main__":
+    main()

mksinewave-1.0.0/mksinewave/sinewave.py

@@ -0,0 +1,108 @@
+import argparse
+import os
+import re
+
+import numpy as np
+import soundfile as sf
+
+
+def parse_frequency(value_str):
+    """Custom argparse type parser to handle strings like 440, 1.4k, 22kHz, etc."""
+    s = value_str.strip().lower()
+
+    match = re.match(r'^(\d*\.?\d+)\s*(k)?(?:hz)?$', s)
+    if not match:
+        raise argparse.ArgumentTypeError(
+            f"Invalid frequency format: '{value_str}'. Use numbers like '440', '1.4k', or '22kHz'."
+        )
+
+    number_part, k_modifier = match.groups()
+    freq = float(number_part)
+
+    if k_modifier:
+        freq *= 1000
+
+    return freq
+
+
+def generate_sine_wave(frequency, duration, sample_rate, fade_in, fade_out, output_file, force, verbose):
+    if os.path.exists(output_file) and not force:
+        print(f"Error: File '{output_file}' already exists. Use -f or --force to overwrite it.")
+        return
+
+    if not (20.0 <= frequency <= 22000.0):
+        print(f"Error: Frequency ({frequency:g} Hz) out of bounds. Must be between 20 Hz and 22,000 Hz.")
+        return
+
+    if frequency >= (sample_rate / 2):
+        print(f"Error: Frequency ({frequency:g} Hz) must be less than half the sample rate ({sample_rate / 2} Hz) to avoid aliasing.")
+        return
+
+    if verbose:
+        print(f"Configuring audio: {frequency:g}Hz for {duration}s at {sample_rate}Hz sample rate.")
+        if fade_in > 0 or fade_out > 0:
+            print(f"Applying fades: Fade-in = {fade_in}s, Fade-out = {fade_out}s")
+
+    total_samples = int(sample_rate * duration)
+    t = np.linspace(0, duration, total_samples, endpoint=False)
+
+    audio = np.sin(2 * np.pi * frequency * t)
+
+    envelope = np.ones(total_samples)
+
+    if fade_in > 0:
+        fade_in_samples = min(int(sample_rate * fade_in), total_samples)
+        envelope[:fade_in_samples] = np.linspace(0.0, 1.0, fade_in_samples)
+
+    if fade_out > 0:
+        fade_out_samples = min(int(sample_rate * fade_out), total_samples)
+        envelope[-fade_out_samples:] = np.linspace(1.0, 0.0, fade_out_samples)
+
+    audio_signals = audio * envelope
+    if verbose:
+        print(f"Writing data to '{output_file}' (inferring container format from extension)...")
+    try:
+        sf.write(output_file, audio_signals, sample_rate)
+        print(f"Success: Saved '{output_file}'")
+    except ValueError as e:
+        print(f"Error: Could not infer format or write file. {e}")
+        print("Supported extensions include: .wav, .flac, .ogg, .aiff")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate a sine wave audio file with flexible frequency inputs.")
+    parser.add_argument("frequency", type=parse_frequency, help="Frequency (e.g., 440, 1.4k, 22kHz)")
+    parser.add_argument("duration", type=float, help="Total duration of the audio in seconds")
+    parser.add_argument("--fade-in", type=float, default=0.0, help="Fade-in duration in seconds (default: 0.0)")
+    parser.add_argument("--fade-out", type=float, default=0.0, help="Fade-out duration in seconds (default: 0.0)")
+    parser.add_argument("-s", "--sample-rate", type=int, default=44100, help="Sample rate in Hz (default: 44100)")
+    parser.add_argument("-o", "--output", type=str, default="sine_wave.wav", help="Output filename with extension (default: sine_wave.wav)")
+
+    parser.add_argument("-f", "--force", action="store_true", help="Overwrite the output file if it already exists")
+    parser.add_argument("-v", "--verbose", action="store_true", help="Increase output verbosity")
+
+    args = parser.parse_args()
+
+    if args.fade_in + args.fade_out > args.duration:
+        parser.error("Combined fade-in and fade-out durations cannot exceed the total file duration.")
+
+    return args
+
+
+def main():
+    args = parse_args()
+
+    generate_sine_wave(
+        frequency=args.frequency,
+        duration=args.duration,
+        sample_rate=args.sample_rate,
+        fade_in=args.fade_in,
+        fade_out=args.fade_out,
+        output_file=args.output,
+        force=args.force,
+        verbose=args.verbose
+    )
+
+
+if __name__ == "__main__":
+    main()

mksinewave-1.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "mksinewave"
+version = "1.0.0"
+description = "Simple command-line tool for creating audio files containing pure sine wave tones"
+authors = [
+    {name = "DJ Stomp",email = "85457381+DJStompZone@users.noreply.github.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+dependencies = [
+    "numpy (>=2.5.3,<3.0.0)",
+    "soundfile (>=0.14.0,<0.15.0)"
+]
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.1.1,<10.0.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest (>=9.1.1,<10.0.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)"
+]
+
+[tool.poetry]
+packages = [{include = "mksinewave"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.scripts]
+mksinewave = "mksinewave.mksinewave:main"
+test-mksinewave = "pytest:main"
+
+[tool.pytest.ini_options]
+addopts = "--cov=mksinewave --cov-report=term-missing --cov-report=html"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["mksinewave"]
+
+[tool.coverage.report]
+fail_under = 95
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "pass"
+]