phonipy 0.1.0__py3-none-any.whl

phonipy/__init__.py

@@ -0,0 +1,26 @@
+"""PhoniPy: voice note stability and harmonic purity, offline and reproducible."""
+
+from .analysis import analyze_file, analyze_samples, frequency_to_key, key_to_frequency
+from .audio import AudioError
+from .batch import BatchResult, analyze_directory, parser
+from .config import AnalysisConfig
+from .metrics import compute_metrics
+from .models import AnalysisResult, Frame, Metrics, Segment
+
+__version__ = "0.1.0"
+__all__ = [
+    "AnalysisConfig",
+    "AnalysisResult",
+    "AudioError",
+    "BatchResult",
+    "Frame",
+    "Metrics",
+    "Segment",
+    "analyze_directory",
+    "analyze_file",
+    "analyze_samples",
+    "compute_metrics",
+    "frequency_to_key",
+    "key_to_frequency",
+    "parser",
+]

phonipy/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

phonipy/analysis.py

@@ -0,0 +1,200 @@
+"""Deterministic short-window harmonic detector and consecutive-note segmentation."""
+
+import math
+
+import numpy as np
+from scipy.fft import irfft, next_fast_len, rfft, rfftfreq
+from scipy.signal import find_peaks
+
+from .audio import load_audio, prepare_audio
+from .config import AnalysisConfig
+from .metrics import compute_metrics
+from .models import AnalysisResult, Frame, Segment
+
+
+def frequency_to_key(frequency):
+    """Fractional MIDI note number, A4=69. Piano-key numbering equals MIDI minus 20."""
+    value = np.asarray(frequency, dtype=float)
+    if np.any(~np.isfinite(value)) or np.any(value <= 0):
+        raise ValueError("Frequency must be positive and finite")
+    answer = 69 + 12 * np.log2(value / 440)
+    return float(answer) if answer.ndim == 0 else answer
+
+
+def key_to_frequency(key):
+    value = np.asarray(key, dtype=float)
+    if np.any(~np.isfinite(value)):
+        raise ValueError("Key must be finite")
+    with np.errstate(over="ignore", under="ignore"):
+        answer = 440 * 2 ** ((value - 69) / 12)
+    if np.any(~np.isfinite(answer)) or np.any(answer <= 0):
+        raise ValueError("Key is outside the representable frequency range")
+    return float(answer) if answer.ndim == 0 else answer
+
+
+class _Detector:
+    def __init__(self, config):
+        self.config = config
+        self.size = round(config.window_ms * config.sample_rate / 1000)
+        self.window = np.hanning(self.size)
+        self.nfft = next_fast_len(4 * self.size)
+        self.frequencies = rfftfreq(self.nfft, 1 / config.sample_rate)
+        self.min_lag = max(1, math.ceil(config.sample_rate / config.fmax))
+        self.max_lag = min(self.size - 2, math.floor(config.sample_rate / config.fmin))
+        # Original window, not zero-padded FFT, sets physical spectral resolution.
+        self.bandwidth = max(config.harmonic_bandwidth_hz, 1.5 * config.sample_rate / self.size)
+
+    def detect(self, frame):
+        cfg = self.config
+        centered = frame - np.mean(frame)
+        rms = float(np.sqrt(np.mean(centered**2)))
+        rms_db = max(-300.0, 20 * math.log10(max(rms, 1e-15)))
+        if rms_db < cfg.min_rms_db:
+            return None, None, None, 0.0, 0.0, rms_db, False
+        # Normalized square difference/autocorrelation supplies periodicity candidates.
+        spectrum = rfft(centered, self.nfft)
+        acf = irfft(np.abs(spectrum) ** 2, self.nfft)[: self.size]
+        energy = np.concatenate(([0.0], np.cumsum(centered**2)))
+        lags = np.arange(self.size)
+        denominator = energy[self.size - lags] + energy[-1] - energy[lags]
+        nsdf = np.divide(2 * acf, denominator, out=np.zeros_like(acf), where=denominator > 1e-20)
+        peaks, _ = find_peaks(nsdf[self.min_lag - 1 : self.max_lag + 2])
+        peaks = peaks + self.min_lag - 1
+        peaks = peaks[(peaks >= self.min_lag) & (peaks <= self.max_lag)]
+        if not len(peaks):
+            return None, None, None, 0.0, 0.0, rms_db, False
+        best = float(np.max(nsdf[peaks]))
+        if best < cfg.min_periodicity:
+            return None, None, None, 0.0, max(0.0, best), rms_db, False
+        candidates = peaks[nsdf[peaks] >= max(cfg.min_periodicity, 0.9 * best)]
+        # Earliest strong periodicity peak avoids selecting integer period multiples.
+        lag = int(candidates[0])
+        a, b, c = nsdf[lag - 1 : lag + 2]
+        divisor = a - 2 * b + c
+        adjustment = 0.5 * (a - c) / divisor if abs(divisor) > 1e-15 else 0.0
+        frequency = float(cfg.sample_rate / (lag + np.clip(adjustment, -0.5, 0.5)))
+        power = np.abs(rfft(centered * self.window, self.nfft)) ** 2
+        power[1:-1] *= 2  # one-sided spectral power
+        total = float(np.sum(power))
+        if total <= 1e-20:
+            return None, None, None, 0.0, best, rms_db, False
+        mask = np.zeros(len(power), dtype=bool)
+        width = min(self.bandwidth, 0.35 * frequency)
+        for harmonic in range(1, cfg.harmonics + 1):
+            target = harmonic * frequency
+            if target >= cfg.sample_rate / 2:
+                break
+            left = np.searchsorted(self.frequencies, target - width)
+            right = np.searchsorted(self.frequencies, target + width, side="right")
+            mask[left:right] = True
+        ratio = float(np.clip(np.sum(power[mask]) / total, 0, 1))
+        band = power[(self.frequencies >= cfg.fmin) & (self.frequencies <= cfg.sample_rate / 2)]
+        flatness = float(np.exp(np.mean(np.log(band + 1e-30))) / (np.mean(band) + 1e-30))
+        fractional = frequency_to_key(frequency)
+        key = int(np.floor(fractional + 0.5))
+        accepted = (
+            cfg.fmin <= frequency <= cfg.fmax
+            and ratio >= cfg.min_energy_ratio
+            and flatness <= cfg.max_flatness
+        )
+        return frequency, key, fractional, ratio, min(1.0, best), rms_db, bool(accepted)
+
+
+def segment_frames(frames, min_frames=8):
+    """Backdate accepted runs to their first frame; invalid frames always end a run."""
+    if isinstance(min_frames, bool) or not isinstance(min_frames, int) or min_frames < 1:
+        raise ValueError("min_frames must be a positive integer")
+    segments = []
+    run = []
+
+    def close():
+        if len(run) >= min_frames:
+            duration = run[-1].end - run[0].start
+            weights = np.array([f.end - f.start for f in run])
+            segments.append(
+                Segment(
+                    run[0].key,
+                    run[0].start,
+                    run[-1].end,
+                    duration,
+                    float(np.average([f.energy_ratio for f in run], weights=weights)),
+                    float(np.average([f.fractional_key for f in run], weights=weights)),
+                    len(run),
+                )
+            )
+
+    for frame in frames:
+        if run and (
+            not frame.accepted
+            or frame.key != run[-1].key
+            or not math.isclose(frame.start, run[-1].end, abs_tol=1e-8)
+        ):
+            close()
+            run = []
+        if frame.accepted:
+            run.append(frame)
+    close()
+    return segments
+
+
+def _analyze(prepared, config, source):
+    samples, duration, warnings, metadata = prepared
+    detector = _Detector(config)
+    hop = round(config.sample_rate * config.hop_ms / 1000)
+    frames = []
+    for start in range(0, len(samples), hop):
+        time = start / config.sample_rate
+        if time >= duration:
+            break
+        chunk = samples[start : start + detector.size]
+        if len(chunk) < detector.size:
+            chunk = np.pad(chunk, (0, detector.size - len(chunk)))
+        frequency, key, fractional, ratio, periodicity, rms_db, accepted = detector.detect(chunk)
+        frames.append(
+            Frame(
+                time,
+                min((start + hop) / config.sample_rate, duration),
+                frequency,
+                key,
+                fractional,
+                ratio,
+                periodicity,
+                rms_db,
+                accepted,
+            )
+        )
+    segments = segment_frames(frames, config.min_frames)
+    if not segments:
+        warnings.append("No stable detections; means and hoarseness are undefined (null)")
+    metadata.update(
+        {
+            "version": "0.1.0",
+            "detector": "nsdf-harmonic-v1",
+            "effective_hop_ms": 1000 * hop / config.sample_rate,
+            "effective_window_ms": 1000 * detector.size / config.sample_rate,
+            "nominal_minimum_run_ms": 1000 * hop * config.min_frames / config.sample_rate,
+            "key_numbering": "MIDI: A4=69; piano-key index = MIDI-20",
+            "frame_count": len(frames),
+        }
+    )
+    return AnalysisResult(
+        source,
+        compute_metrics(segments, duration, config.reference_key),
+        segments,
+        frames,
+        config.to_dict(),
+        metadata,
+        warnings,
+    )
+
+
+def analyze_samples(samples, sample_rate, config=None, *, source="<array>"):
+    """Analyze mono/stereo PCM arrays. Integer PCM is scaled to floating PCM units."""
+    config = config or AnalysisConfig()
+    return _analyze(prepare_audio(samples, sample_rate, config), config, source)
+
+
+def analyze_file(path, config=None):
+    """Decode a supported audio file and return all metrics, segments and frames."""
+    config = config or AnalysisConfig()
+    return _analyze(load_audio(path, config), config, str(path))

phonipy/app.py

@@ -0,0 +1,92 @@
+"""Run with: streamlit run <installed phonipy/app.py path>."""
+
+import io
+import json
+from dataclasses import asdict
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import soundfile as sf
+import streamlit as st
+
+from phonipy import AnalysisConfig, analyze_samples
+
+
+def main():
+    st.set_page_config(page_title="PhoniPy", page_icon="🎵", layout="wide")
+    st.title("PhoniPy")
+    st.caption("Voice stability and harmonic purity · research software")
+    with st.sidebar:
+        st.header("Analysis settings")
+        preset = st.selectbox("Voice range / task", ["general", "low", "high", "speech", "singing"])
+        reference = st.number_input("Reference note (MIDI; A4 = 69)", value=69.0)
+        minimum = st.number_input("Minimum consecutive frames", min_value=1, value=8)
+        periodicity = st.slider("Minimum periodicity", 0.0, 1.0, 0.65)
+        config = AnalysisConfig.preset(
+            preset,
+            reference_key=reference,
+            min_frames=int(minimum),
+            min_periodicity=periodicity,
+            max_duration=300.0,
+        )
+        st.download_button(
+            "Download settings",
+            json.dumps(config.to_dict(), indent=2),
+            "phonipy-config.json",
+            "application/json",
+        )
+    st.write("Upload solo voice recordings. Start with a sustained vowel or a single-note hold.")
+    st.info(
+        "These experimental measurements are not a diagnosis. Speech and intentional "
+        "note changes can naturally produce fragmented stable-note detections."
+    )
+    uploads = st.file_uploader(
+        "Audio files (up to 5 minutes each)",
+        type=["wav", "flac", "ogg", "aiff", "mp3"],
+        accept_multiple_files=True,
+    )
+    if not st.button("Analyze recordings", type="primary", disabled=not uploads):
+        return
+    rows, payloads = [], []
+    progress = st.progress(0.0)
+    for index, upload in enumerate(uploads):
+        try:
+            if upload.size > 100 * 1024 * 1024:
+                raise ValueError("File exceeds the 100 MB dashboard limit")
+            with sf.SoundFile(io.BytesIO(upload.getvalue())) as handle:
+                if handle.frames / handle.samplerate > config.max_duration:
+                    raise ValueError("Recording exceeds the five-minute dashboard limit")
+                rate = handle.samplerate
+                samples = handle.read(always_2d=True)
+            result = analyze_samples(samples, rate, config, source=upload.name)
+            rows.append({"file": upload.name, **asdict(result.metrics)})
+            payloads.append(result.to_dict(include_frames=True))
+            with st.expander(upload.name, expanded=len(uploads) == 1):
+                st.audio(upload.getvalue())
+                for warning in result.warnings:
+                    st.warning(warning)
+                figure = result.plot()
+                st.pyplot(figure)
+                plt.close(figure)
+                st.dataframe(pd.DataFrame([asdict(s) for s in result.segments]))
+        except (ValueError, OSError, RuntimeError) as exc:
+            st.error(f"{upload.name}: {exc}")
+            payloads.append({"source": upload.name, "error": str(exc)})
+        progress.progress((index + 1) / len(uploads))
+    if rows:
+        table = pd.DataFrame(rows)
+        st.subheader("Recording metrics")
+        st.dataframe(table, hide_index=True)
+        st.download_button(
+            "Download metrics CSV", table.to_csv(index=False), "phonipy-metrics.csv", "text/csv"
+        )
+    st.download_button(
+        "Download full results JSON",
+        json.dumps(payloads, allow_nan=False),
+        "phonipy-results.json",
+        "application/json",
+    )
+
+
+if __name__ == "__main__":
+    main()

phonipy/audio.py

@@ -0,0 +1,106 @@
+"""Audio decoding and explicit input quality handling."""
+
+from math import gcd
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+from scipy.signal import resample_poly
+
+from .config import AnalysisConfig
+
+
+class AudioError(ValueError):
+    """A recording cannot be decoded or analyzed safely."""
+
+
+def prepare_audio(samples, sample_rate, config: AnalysisConfig):
+    if (
+        isinstance(sample_rate, bool)
+        or not isinstance(sample_rate, (int, np.integer))
+        or not 1000 <= sample_rate <= 384000
+    ):
+        raise AudioError("sample_rate must be an integer between 1000 and 384000 Hz")
+    data = np.asarray(samples)
+    if data.ndim not in (1, 2) or data.size == 0 or (data.ndim == 2 and data.shape[1] == 0):
+        raise AudioError("Audio must be a nonempty samples or samples-by-channels array")
+    if data.dtype.kind not in "fiu":
+        raise AudioError("Audio samples must be real numeric values")
+    if len(data) / sample_rate > config.max_duration:
+        raise AudioError(f"Recording exceeds max_duration={config.max_duration} seconds")
+    if data.dtype.kind in "iu":
+        info = np.iinfo(data.dtype)
+        if data.dtype.kind == "u":
+            midpoint = (int(info.max) + 1) / 2
+            data = (data.astype(np.float64) - midpoint) / midpoint
+        else:
+            data = data.astype(np.float64) / max(abs(int(info.min)), int(info.max))
+    else:
+        data = data.astype(np.float64, copy=True)
+    warnings = []
+    if not np.isfinite(data).all():
+        if config.nonfinite == "error":
+            raise AudioError("Audio contains NaN or infinity; use nonfinite='zero' to repair")
+        data[~np.isfinite(data)] = 0
+        warnings.append("Nonfinite samples replaced with zero by explicit configuration")
+    if np.max(np.abs(data)) > 8:
+        raise AudioError("Floating audio must use normalized PCM units (approximately -1 to 1)")
+    if np.any(np.abs(data) >= 0.999):
+        warnings.append("Samples approach/exceed full scale; clipping may affect measurements")
+    channels = 1 if data.ndim == 1 else data.shape[1]
+    selected = None
+    if data.ndim == 2:
+        if config.channel == "mix":
+            data = data.mean(axis=1)
+        else:
+            selected = (
+                int(np.argmax(np.mean(data**2, axis=0)))
+                if config.channel == "loudest"
+                else int(config.channel == "right")
+            )
+            if selected >= channels:
+                raise AudioError("Requested right channel is absent")
+            data = data[:, selected]
+        if channels > 1:
+            warnings.append(f"Multichannel input: {config.channel} channel policy applied")
+    elif config.channel == "right":
+        raise AudioError("Requested right channel is absent")
+    duration = len(data) / sample_rate
+    if abs(np.mean(data)) > 0.01:
+        warnings.append("DC offset detected; each analysis frame is mean-centered")
+    if sample_rate / 2 <= config.fmax:
+        raise AudioError("Input Nyquist frequency must exceed configured fmax")
+    if sample_rate != config.sample_rate:
+        divisor = gcd(int(sample_rate), config.sample_rate)
+        data = resample_poly(data, config.sample_rate // divisor, int(sample_rate) // divisor)
+    if len(data) < round(config.window_ms * config.sample_rate / 1000):
+        warnings.append("Input is shorter than one analysis window; zero-padding applied")
+    return (
+        data,
+        duration,
+        warnings,
+        {
+            "original_sample_rate": int(sample_rate),
+            "analysis_sample_rate": config.sample_rate,
+            "channels": channels,
+            "selected_channel": selected,
+            "sample_count": len(samples),
+        },
+    )
+
+
+def load_audio(path, config):
+    path = Path(path)
+    if not path.is_file():
+        raise AudioError(f"Audio file does not exist: {path}")
+    try:
+        with sf.SoundFile(path) as handle:
+            if handle.frames / handle.samplerate > config.max_duration:
+                raise AudioError(f"Recording exceeds max_duration={config.max_duration} seconds")
+            samples = handle.read(dtype="float64", always_2d=True)
+            rate = handle.samplerate
+    except AudioError:
+        raise
+    except (sf.LibsndfileError, OSError, ValueError) as exc:
+        raise AudioError(f"Cannot decode {path.name}: {exc}") from exc
+    return prepare_audio(samples, rate, config)

phonipy/batch.py

@@ -0,0 +1,158 @@
+"""Batch processing in the spirit of midipy, with per-file error isolation."""
+
+import csv
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+
+from .analysis import analyze_file
+from .config import AnalysisConfig
+from .models import AnalysisResult, Metrics
+
+EXTENSIONS = {".wav", ".flac", ".ogg", ".aiff", ".aif", ".mp3", ".au", ".snd"}
+
+
+@dataclass
+class BatchResult:
+    results: list[AnalysisResult]
+    errors: list[dict]
+    config: dict
+
+    @property
+    def rows(self):
+        return [
+            {
+                "source": r.source,
+                "status": "ok",
+                **asdict(r.metrics),
+                "warnings": " | ".join(r.warnings),
+            }
+            for r in self.results
+        ]
+
+    def save(self, path):
+        """Write an atomic summary; CSV/XLSX also receive a structured error sidecar."""
+        path = Path(path)
+        suffix = path.suffix.lower()
+        if suffix not in (".json", ".csv", ".xlsx"):
+            raise ValueError("Output extension must be .json, .csv or .xlsx")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary = tempfile.mkstemp(dir=path.parent, suffix=suffix)
+        os.close(descriptor)
+        temporary = Path(temporary)
+        try:
+            if suffix == ".json":
+                temporary.write_text(
+                    json.dumps(
+                        {
+                            "config": self.config,
+                            "results": [r.to_dict() for r in self.results],
+                            "errors": self.errors,
+                        },
+                        indent=2,
+                        allow_nan=False,
+                    )
+                    + "\n",
+                    encoding="utf-8",
+                )
+            else:
+                columns = [
+                    "source",
+                    "status",
+                    *[f.name for f in fields(Metrics)],
+                    "warnings",
+                    "error",
+                ]
+                rows = self.rows + [
+                    {"source": e["source"], "status": "error", "error": e["error"]}
+                    for e in self.errors
+                ]
+                if suffix == ".csv":
+                    with temporary.open("w", newline="", encoding="utf-8") as handle:
+                        writer = csv.DictWriter(handle, fieldnames=columns)
+                        writer.writeheader()
+                        writer.writerows(rows)
+                else:
+                    try:
+                        from openpyxl import Workbook
+                    except ImportError as exc:
+                        raise ImportError("Install phonipy[excel] for XLSX output") from exc
+                    book = Workbook()
+                    sheet = book.active
+                    sheet.title = "Metrics"
+                    sheet.append(columns)
+                    for row in rows:
+                        # Force strings to text to avoid interpreting source filenames as formulas.
+                        sheet.append([row.get(c) for c in columns])
+                        for cell in sheet[sheet.max_row]:
+                            if isinstance(cell.value, str):
+                                cell.data_type = "s"
+                    sheet.freeze_panes = "A2"
+                    book.save(temporary)
+                sidecar = path.with_suffix(path.suffix + ".metadata.json")
+                sidecar.write_text(
+                    json.dumps(
+                        {
+                            "config": self.config,
+                            "errors": self.errors,
+                            "recordings": [
+                                {"source": r.source, "metadata": r.metadata, "warnings": r.warnings}
+                                for r in self.results
+                            ],
+                        },
+                        indent=2,
+                        allow_nan=False,
+                    )
+                    + "\n",
+                    encoding="utf-8",
+                )
+            os.replace(temporary, path)
+        finally:
+            temporary.unlink(missing_ok=True)
+        return path
+
+
+def analyze_directory(source, config=None, *, recursive=False, strict=False, progress=None):
+    config = config or AnalysisConfig()
+    directory = Path(source)
+    if not directory.is_dir():
+        raise ValueError(f"Input directory does not exist: {directory}")
+    paths = sorted(
+        p
+        for p in (directory.rglob("*") if recursive else directory.iterdir())
+        if p.is_file() and p.suffix.lower() in EXTENSIONS
+    )
+    if not paths:
+        raise ValueError(f"No supported audio files found in {directory}")
+    results, errors = [], []
+    for index, path in enumerate(paths):
+        try:
+            results.append(analyze_file(path, config))
+        except (ValueError, OSError, RuntimeError) as exc:
+            if strict:
+                raise
+            errors.append({"source": str(path), "type": type(exc).__name__, "error": str(exc)})
+        if progress:
+            progress(index + 1, len(paths), str(path))
+    return BatchResult(results, errors, config.to_dict())
+
+
+def parser(source, metrics=None, output_format="csv", save_path="Output", **kwargs):
+    """midipy-style convenience API; returns a DataFrame (requires pandas)."""
+    import pandas as pd
+
+    result = analyze_directory(source, **kwargs)
+    table = pd.DataFrame(result.rows)
+    if metrics is not None and metrics != ["all"]:
+        unknown = set(metrics) - set(table.columns)
+        if unknown:
+            raise ValueError(f"Unknown metrics: {sorted(unknown)}")
+        table = table.loc[:, metrics]
+    if output_format not in ("csv", "json", "xlsx", "excel"):
+        raise ValueError("output_format must be csv, json, xlsx or excel")
+    extension = "xlsx" if output_format == "excel" else output_format
+    result.save(f"{save_path}.{extension}")
+    table.attrs["errors"] = result.errors
+    return table

phonipy/cli.py

@@ -0,0 +1,78 @@
+"""Command-line batch/single-file entry point. No network or telemetry."""
+
+import argparse
+import csv
+import sys
+from dataclasses import fields, replace
+from pathlib import Path
+
+from . import __version__
+from .analysis import analyze_file
+from .batch import BatchResult, analyze_directory
+from .config import AnalysisConfig
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="PhoniPy voice stability analysis")
+    parser.add_argument("input", type=Path, help="Audio file or directory")
+    parser.add_argument("-o", "--output", type=Path, default=Path("phonipy-results.json"))
+    parser.add_argument("--config", type=Path, help="JSON configuration file")
+    parser.add_argument("--preset", choices=["general", "low", "high", "speech", "singing"])
+    parser.add_argument("--reference-key", type=float, help="Fractional MIDI note; A4=69")
+    parser.add_argument("--recursive", action="store_true")
+    parser.add_argument("--strict", action="store_true", help="Stop on the first failed file")
+    parser.add_argument("--details", type=Path, help="Directory for frame/segment JSON and CSV")
+    parser.add_argument("--plot", action="store_true", help="Save composite PNGs in --details")
+    parser.add_argument("--version", action="version", version=__version__)
+    args = parser.parse_args(argv)
+    if args.config and args.preset:
+        parser.error("Choose --config or --preset, not both")
+    if args.plot and not args.details:
+        parser.error("--plot requires --details DIR")
+    try:
+        config = (
+            AnalysisConfig.from_json(args.config)
+            if args.config
+            else AnalysisConfig.preset(args.preset or "general")
+        )
+        if args.reference_key is not None:
+            config = replace(config, reference_key=args.reference_key)
+        if args.input.is_dir():
+            batch = analyze_directory(
+                args.input, config, recursive=args.recursive, strict=args.strict
+            )
+        else:
+            batch = BatchResult([analyze_file(args.input, config)], [], config.to_dict())
+        batch.save(args.output)
+        if args.details:
+            args.details.mkdir(parents=True, exist_ok=True)
+            for index, result in enumerate(batch.results):
+                # Numeric prefix prevents collisions between equal filenames in subfolders.
+                name = f"{index:05d}-{Path(result.source).stem}"
+                result.to_json(args.details / f"{name}.json", include_frames=True)
+                for label in ("frames", "segments"):
+                    records = getattr(result, label)
+                    if records:
+                        from dataclasses import asdict
+
+                        with (args.details / f"{name}-{label}.csv").open(
+                            "w", newline="", encoding="utf-8"
+                        ) as handle:
+                            writer = csv.DictWriter(
+                                handle, fieldnames=[f.name for f in fields(records[0])]
+                            )
+                            writer.writeheader()
+                            writer.writerows(asdict(record) for record in records)
+                if args.plot:
+                    import matplotlib.pyplot as plt
+
+                    figure = result.plot(args.details / f"{name}.png")
+                    plt.close(figure)
+        print(
+            f"Analyzed {len(batch.results)} file(s); {len(batch.errors)} error(s). "
+            f"Saved {args.output}"
+        )
+        return 1 if batch.errors else 0
+    except (ValueError, OSError, RuntimeError, ImportError, TypeError) as exc:
+        print(f"phonipy: {exc}", file=sys.stderr)
+        return 2

phonipy/config.py

@@ -0,0 +1,80 @@
+"""Explicit, serializable detector settings. Note indices use MIDI numbering (A4=69)."""
+
+import json
+import math
+from dataclasses import asdict, dataclass, replace
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AnalysisConfig:
+    sample_rate: int = 16000
+    hop_ms: float = 17.25
+    window_ms: float = 69.0
+    min_frames: int = 8
+    fmin: float = 65.0
+    fmax: float = 1100.0
+    reference_key: float = 69.0
+    harmonics: int = 12
+    min_rms_db: float = -60.0
+    min_periodicity: float = 0.65
+    min_energy_ratio: float = 0.15
+    max_flatness: float = 0.6
+    harmonic_bandwidth_hz: float = 22.0
+    channel: str = "loudest"
+    nonfinite: str = "error"
+    max_duration: float = 3600.0
+
+    def __post_init__(self):
+        for name in ("sample_rate", "min_frames", "harmonics"):
+            value = getattr(self, name)
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise ValueError(f"{name} must be a positive integer")
+        for name, value in asdict(self).items():
+            if isinstance(value, (float, int)) and not math.isfinite(value):
+                raise ValueError(f"{name} must be finite")
+        if not 4000 <= self.sample_rate <= 192000:
+            raise ValueError("sample_rate must be between 4000 and 192000 Hz")
+        if not 0 < self.hop_ms <= self.window_ms <= 500:
+            raise ValueError("Require 0 < hop_ms <= window_ms <= 500")
+        if round(self.hop_ms * self.sample_rate / 1000) < 1:
+            raise ValueError("hop_ms is shorter than one sample")
+        if not 20 <= self.fmin < self.fmax < self.sample_rate / 2:
+            raise ValueError("Require 20 <= fmin < fmax < Nyquist frequency")
+        if self.window_ms / 1000 * self.fmin < 2:
+            raise ValueError("window_ms must contain at least two cycles at fmin")
+        for name in ("min_periodicity", "min_energy_ratio", "max_flatness"):
+            if not 0 <= getattr(self, name) <= 1:
+                raise ValueError(f"{name} must be between 0 and 1")
+        if not -160 <= self.min_rms_db <= 0:
+            raise ValueError("min_rms_db must be between -160 and 0 dBFS")
+        if self.harmonic_bandwidth_hz <= 0 or self.max_duration <= 0:
+            raise ValueError("Bandwidth and max_duration must be positive")
+        if self.harmonics > 128:
+            raise ValueError("harmonics must not exceed 128")
+        if self.channel not in ("loudest", "mix", "left", "right"):
+            raise ValueError("channel must be loudest, mix, left or right")
+        if self.nonfinite not in ("error", "zero"):
+            raise ValueError("nonfinite must be error or zero")
+
+    def to_dict(self):
+        return asdict(self)
+
+    @classmethod
+    def from_json(cls, path):
+        """Reject unknown fields and invalid values instead of guessing."""
+        return cls(**json.loads(Path(path).read_text(encoding="utf-8")))
+
+    @classmethod
+    def preset(cls, name="general", **overrides):
+        """Task/range presets; ranges describe pitch, not a person's sex."""
+        presets = {
+            "general": {},
+            "low": {"fmin": 50.0, "fmax": 500.0, "window_ms": 86.25},
+            "high": {"fmin": 130.0, "fmax": 1400.0},
+            "speech": {"fmin": 65.0, "fmax": 600.0},
+            "singing": {"fmin": 50.0, "fmax": 1600.0, "window_ms": 86.25},
+        }
+        if name not in presets:
+            raise ValueError(f"Unknown preset {name!r}; choose {', '.join(presets)}")
+        return replace(cls(**presets[name]), **overrides)

phonipy/metrics.py

@@ -0,0 +1,56 @@
+"""The manuscript's ten global parameters, with undefined means represented by None."""
+
+import math
+
+from .models import Metrics, Segment
+
+
+def compute_metrics(segments: list[Segment], raw_duration: float, reference_key=69.0):
+    if not math.isfinite(raw_duration) or raw_duration < 0:
+        raise ValueError("raw_duration must be finite and nonnegative")
+    if not math.isfinite(reference_key):
+        raise ValueError("reference_key must be finite")
+    previous_end = 0.0
+    for segment in segments:
+        values = (
+            segment.start,
+            segment.end,
+            segment.duration,
+            segment.mean_energy,
+            segment.mean_fractional_key,
+        )
+        if not all(math.isfinite(v) for v in values):
+            raise ValueError("Segment values must be finite")
+        if (
+            segment.start < previous_end - 1e-9
+            or segment.end > raw_duration + 1e-9
+            or segment.start < 0
+            or segment.duration <= 0
+            or not math.isclose(
+                segment.duration, segment.end - segment.start, rel_tol=1e-8, abs_tol=1e-9
+            )
+            or not 0 <= segment.mean_energy <= 1
+        ):
+            raise ValueError("Segments must be ordered, disjoint and inside the recording")
+        previous_end = segment.end
+    count = len(segments)
+    if count == 0:
+        return Metrics(raw_duration, 0.0, 0.0, None, None, None, None, 0.0, 0.0, 0)
+    valid = math.fsum(s.duration for s in segments)
+    active = segments[-1].end - segments[0].start
+    energy = math.fsum(s.duration * s.mean_energy for s in segments) / valid
+    average = valid / count
+    # Unweighted mean across detections, preserving fractional estimated pitch.
+    offset = math.fsum(s.mean_fractional_key - reference_key for s in segments) / count
+    return Metrics(
+        raw_duration,
+        active,
+        valid,
+        offset,
+        energy,
+        (1 - energy) * 100,
+        average,
+        average / valid,
+        min(1.0, valid / active),
+        count,
+    )

phonipy/models.py

@@ -0,0 +1,72 @@
+"""Plain data structures with JSON-safe, explicit missing measurements."""
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Frame:
+    start: float
+    end: float
+    frequency: float | None
+    key: int | None
+    fractional_key: float | None
+    energy_ratio: float
+    periodicity: float
+    rms_db: float
+    accepted: bool
+
+
+@dataclass(frozen=True)
+class Segment:
+    key: int
+    start: float
+    end: float
+    duration: float
+    mean_energy: float
+    mean_fractional_key: float
+    frame_count: int
+
+
+@dataclass(frozen=True)
+class Metrics:
+    raw_duration: float
+    active_time: float
+    valid_time: float
+    average_offset: float | None
+    average_energy: float | None
+    hoarseness: float | None
+    average_duration: float | None
+    continuity: float
+    sparsity: float
+    breakouts: int
+
+
+@dataclass
+class AnalysisResult:
+    source: str
+    metrics: Metrics
+    segments: list[Segment]
+    frames: list[Frame]
+    config: dict
+    metadata: dict
+    warnings: list[str] = field(default_factory=list)
+
+    def to_dict(self, include_frames=False):
+        result = asdict(self)
+        if not include_frames:
+            result.pop("frames")
+        return result
+
+    def to_json(self, path=None, include_frames=False):
+        value = json.dumps(self.to_dict(include_frames), indent=2, allow_nan=False)
+        if path is not None:
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+            Path(path).write_text(value + "\n", encoding="utf-8")
+        return value
+
+    def plot(self, path=None):
+        from .plotting import composite_plot
+
+        return composite_plot(self, path)

phonipy/plotting.py

@@ -0,0 +1,50 @@
+"""The manuscript's composite harmonic-purity / stable-note plot."""
+
+
+def composite_plot(result, path=None):
+    try:
+        from matplotlib.backends.backend_agg import FigureCanvasAgg
+        from matplotlib.figure import Figure
+    except ImportError as exc:
+        raise ImportError("Install phonipy[plot] to generate composite plots") from exc
+    figure = Figure(figsize=(12, 4), layout="constrained")
+    FigureCanvasAgg(figure)
+    axis = figure.subplots()
+    axis.plot(
+        [f.start for f in result.frames],
+        [f.energy_ratio for f in result.frames],
+        color="0.45",
+        linewidth=0.8,
+        label="Harmonic energy ratio",
+    )
+    for segment in result.segments:
+        axis.axvspan(segment.start, segment.end, alpha=0.1, color="blue")
+        axis.scatter([segment.start], [segment.mean_energy], color="blue", s=20)
+        axis.annotate(
+            str(segment.key),
+            (segment.start, segment.mean_energy),
+            xytext=(2, 8),
+            textcoords="offset points",
+            fontsize=8,
+            color="blue",
+        )
+        axis.scatter([segment.end], [segment.mean_energy], color="red", s=20)
+        axis.annotate(
+            f"{segment.frame_count} frames",
+            (segment.end, segment.mean_energy),
+            xytext=(2, -14),
+            textcoords="offset points",
+            fontsize=7,
+            color="red",
+        )
+    axis.set(
+        xlabel="Time (seconds)",
+        ylabel="Harmonic-series / total energy",
+        ylim=(0, 1.1),
+        xlim=(0, max(result.metrics.raw_duration, 0.01)),
+        title="PhoniPy — stable notes (MIDI numbering) and harmonic purity",
+    )
+    axis.legend(loc="lower right")
+    if path:
+        figure.savefig(path, dpi=160)
+    return figure

phonipy-0.1.0.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: phonipy
+Version: 0.1.0
+Summary: Reproducible musical-note stability and harmonic-purity analysis of voice recordings
+Project-URL: Homepage, https://github.com/udanish50/PhoniPy
+Project-URL: Issues, https://github.com/udanish50/PhoniPy/issues
+Author: Muhammad Umair Danish
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,music-therapy,phonation,pitch,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: soundfile>=0.12
+Provides-Extra: app
+Requires-Dist: matplotlib>=3.7; extra == 'app'
+Requires-Dist: pandas>=2; extra == 'app'
+Requires-Dist: streamlit>=1.40; extra == 'app'
+Provides-Extra: benchmark
+Requires-Dist: certifi>=2026.10.19; extra == 'benchmark'
+Requires-Dist: wfdb>=4.1; extra == 'benchmark'
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == 'excel'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Provides-Extra: test
+Requires-Dist: build>=1.2; extra == 'test'
+Requires-Dist: matplotlib>=3.7; extra == 'test'
+Requires-Dist: openpyxl>=3.1; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: ruff>=0.9; extra == 'test'
+Requires-Dist: twine>=6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# PhoniPy
+
+Reproducible musical-note stability and harmonic-purity analysis for solo voice recordings.
+PhoniPy reads audio, detects stable note intervals, computes all ten parameters from
+*Musical-Key Stability Analysis of Continuous Voice*, and exports recording summaries,
+frame data, segment data, and composite plots.
+
+**Research software, version 0.1.0.** The detector is an explicitly documented implementation
+of the manuscript's framework, not a verified reproduction of its unavailable prototype.
+The manuscript's clinical claims and thresholds are not validated by this package.
+
+## Install
+
+```bash
+pip install phonipy
+# Optional exports, plots, dashboard:
+pip install 'phonipy[excel,plot,app]'
+```
+
+Python 3.10 or newer. Core dependencies: NumPy, SciPy, and SoundFile/libsndfile.
+WAV, FLAC, OGG, AIFF and other libsndfile-supported formats are accepted. MP3 support
+depends on the installed libsndfile build; unsupported codecs produce a per-file error.
+For compressed video/audio containers such as M4A, convert to PCM WAV first.
+
+## Python API
+
+```python
+from phonipy import AnalysisConfig, analyze_file, analyze_directory
+
+config = AnalysisConfig.preset("speech", reference_key=57)  # A3, MIDI numbering
+result = analyze_file("voice.wav", config)
+print(result.metrics)
+result.to_json("voice-results.json", include_frames=True)
+result.plot("voice-composite.png")  # requires phonipy[plot]
+
+batch = analyze_directory("recordings", config, recursive=True)
+batch.save("results.csv")  # also JSON or XLSX; failures are retained
+print(batch.errors)
+```
+
+The package also accepts NumPy arrays with `analyze_samples(samples, sample_rate, config)`.
+Arrays use samples-by-channels order; integer PCM is scaled automatically. Floating PCM
+should be approximately within -1 to 1. No automatic gain normalization is performed.
+
+### Familiar midipy-style batch API
+
+```python
+from phonipy import parser
+
+table = parser(
+    "recordings",
+    metrics=["source", "valid_time", "average_energy", "breakouts"],
+    output_format="csv",
+    save_path="VoiceOutput",
+)
+```
+
+`parser` requires pandas (included with `phonipy[app]`). `metrics` selects returned DataFrame
+columns; the saved analysis summary always retains all ten metrics and failures for auditing.
+Prefer the core batch API when pandas is not needed. No outputs are created by analysis
+functions until an explicit save/export call.
+
+## Command line
+
+```bash
+phonipy voice.wav -o result.json --reference-key 57 --details details --plot
+phonipy recordings -o results.csv --recursive --preset speech
+python -m phonipy recordings -o results.xlsx --config examples/config.json
+```
+
+Exit codes: **0** complete success, **1** batch completed with failed files, **2** invalid
+input/settings/output or a single-file failure. Batch processing continues after corrupt
+files by default; `--strict` stops on the first failure. JSON includes settings, warnings,
+and failures; CSV/XLSX include failure rows plus a `.metadata.json` sidecar. `--details`
+adds full JSON and frame/segment CSVs. Duplicate filenames receive distinct numeric prefixes.
+
+## Local dashboard
+
+```bash
+pip install 'phonipy[app]'
+streamlit run "$(python -c 'import phonipy.app; print(phonipy.app.__file__)')"
+```
+
+Upload multiple files, adjust settings, view composite plots, and download CSV/JSON.
+Analysis runs locally without uploads to an analysis service or telemetry from PhoniPy.
+The dashboard limits each recording to five minutes and 100 MB.
+
+## The ten metrics
+
+Let `d_i = end_i - start_i` for each valid stable-note segment; `N` is the segment count.
+
+| Metric | Definition | Unit |
+| --- | --- | --- |
+| `raw_duration` | Original sample count / original sample rate | s |
+| `active_time` | Last valid offset − first valid onset | s |
+| `valid_time` | Sum of valid segment durations | s |
+| `average_offset` | Unweighted segment mean of fractional pitch − reference note | semitones |
+| `average_energy` | Duration-weighted harmonic-energy ratio across valid intervals | 0–1 |
+| `hoarseness` | `(1 - average_energy) * 100` | % |
+| `average_duration` | `valid_time / N` | s |
+| `continuity` | `average_duration / valid_time` | dimensionless |
+| `sparsity` | `valid_time / active_time` | 0–1 |
+| `breakouts` | `N`, including the initial acquisition | count |
+
+No valid detections: time totals, breakouts, continuity and sparsity are zero; undefined
+means and hoarseness are `null` in JSON and blank in CSV/XLSX. **Continuity equals `1/N`**
+whenever N > 0; it is retained exactly as specified, not presented as an independent metric.
+The manuscript uses two inconsistent descriptions of breakouts; this package follows
+Appendix A's segment count. Signed pitch offsets can cancel. `hoarseness` is the manuscript's
+name for an acoustic residual-energy transform, not a clinical hoarseness rating.
+
+## Detector and reproducibility
+
+- Default analysis rate: 16 kHz; hop: 17.25 ms (276 samples); Hann window: 69 ms.
+- Normalized autocorrelation supplies candidate periods; the earliest sufficiently strong
+  local peak is refined with parabolic interpolation. This makes the fundamental candidate
+  stage explicit where the manuscript only says "strongest harmonic series."
+- Harmonic-series energy is measured from a one-sided Hann-windowed power spectrum in
+  nonoverlapping frequency bands around up to 12 harmonics; total energy includes all bins.
+- RMS, periodicity, spectral flatness, pitch range, and harmonic ratio gate detections.
+- The identical rounded MIDI note must persist for at least eight frames. Accepted runs are
+  backdated to their first frame, not the eighth. Invalid/unvoiced frames end a run.
+- Each frame represents a hop interval. Durations use disjoint intervals and the last interval
+  is clipped to the original duration. Forward-looking windows are zero-padded at the end.
+  Overlapping spectral windows do not create overlapping measured durations.
+- Fractional pitch is retained separately for pitch offset. A4=440 Hz is MIDI note 69;
+  traditional 88-key piano index = MIDI number minus 20. Differences are identical.
+- All effective settings, sample rates, channel selection, and warnings are exported.
+
+See [methodology](docs/methodology.md) for equations and limitations.
+
+## Input handling and limits
+
+Stereo/multichannel recordings select the loudest channel by default to avoid phase cancellation.
+Choose `channel="mix"`, `"left"`, or `"right"` explicitly if desired. Resampling is polyphase.
+NaN/infinite samples raise an error unless `nonfinite="zero"` explicitly enables replacement.
+Empty/corrupt inputs, absent channels, invalid ranges, unavailable codecs, and excessive
+durations produce actionable errors. Clipping/DC offset and short input produce warnings.
+The default one-hour duration cap is configurable. Audio and frame results are held in memory;
+split very large recordings into tasks. Output failures are surfaced rather than silently ignored.
+
+Use quiet, solo voice recordings with consistent microphones and levels. Stable vowels and
+single-note holds are the clearest tasks. Speech has natural unvoiced intervals and singing
+has intentional pitch changes; their scores should not be directly compared with vowel scores.
+Noise, reverberation, vibrato, note-boundary quantization, and octave errors can affect results.
+No automatic recovery can reconstruct information absent from a recording.
+
+## Tests and benchmarks
+
+```bash
+pip install -e '.[test,app,benchmark]'
+pytest --cov=phonipy --cov-report=term-missing
+ruff check .
+python benchmarks/download.py --data-dir benchmarks/data
+python benchmarks/run.py --data-dir benchmarks/data --output benchmarks/results
+python -m build
+python -m twine check dist/*
+```
+
+The benchmark scripts analyze synthetic signals with known pitch/timing, all 3,000 recordings
+in a pinned Free Spoken Digit Dataset snapshot, and all 208 VOICED sustained-vowel records.
+They record source hashes, settings, dependency versions, wall time, failures, and per-file metrics.
+Real recordings have no ground-truth values for these novel metrics: those runs demonstrate
+processing coverage, not clinical accuracy or disease classification.
+See [benchmark protocol](benchmarks/README.md) and [results](docs/benchmark-results.md).
+
+## Attribution and license
+
+Implementation: Muhammad Umair Danish. Scientific framework: the user-supplied manuscript
+*Musical-Key Stability Analysis of Continuous Voice: A Methodology for Quantifying Phonatory
+Continuity and Purity in Neurological Disorders with Applications in Music Therapy*, by
+Demian Kogutek and Danish Umair Muhammad. The manuscript itself is not redistributed.
+
+Code: MIT. Benchmark recordings retain their upstream licenses and are not bundled in
+the wheel/source distribution. See the benchmark protocol for dataset citations.

phonipy-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+phonipy/__init__.py,sha256=rZfaoE9Ad95XYuDeUEFzc7HEDfzjNuylC3TSWlVx4DY,706
+phonipy/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+phonipy/analysis.py,sha256=SSFmq2-a7A8Sx9qgDEMQs2Lp8tni1_9fHOkNmdS87XA,8370
+phonipy/app.py,sha256=BOjLQHgkY7ukbT7DSwOyplm-TrLC2AoFBsLfBJZbOCY,3720
+phonipy/audio.py,sha256=8TDY2MSCK27B3QW13SogPVp5YtielhwJ5_LmnoLhIcM,4424
+phonipy/batch.py,sha256=IYnnujMc2Ja8KVA0L_ON2RSy5cNJmJdhmKx22LIg6Ho,6060
+phonipy/cli.py,sha256=ks8IoL7KRSYuygslStFqdGSsF8uNCiS-CubAzFc3eco,3687
+phonipy/config.py,sha256=VAlqP3XRp1Qn7Ex8rl_W75wkjl8kAz546TIEsGBcefY,3539
+phonipy/metrics.py,sha256=NOnm5m6rITWnqFHbjr95iUFZ6NGmUMTGu-wcYqmaPwg,2049
+phonipy/models.py,sha256=1DFB_wJyOn3Fb-obAc-ANIm1a-TGHs04ucRv_EhiBCk,1698
+phonipy/plotting.py,sha256=w40l5mB3LOr7NuaU9b3LXYmYqtTJBHgxGwmMf0T2bZ4,1772
+phonipy-0.1.0.dist-info/METADATA,sha256=CeFjFepKh4DLVsFQJSGU_zhq_FCU7ugojYQL8M-kh50,10284
+phonipy-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+phonipy-0.1.0.dist-info/entry_points.txt,sha256=-Zo5xNYPnOAfnL6wXdAtAWXCHI681WkBu3Czch5ZQWk,45
+phonipy-0.1.0.dist-info/licenses/LICENSE,sha256=JLY-8B0S8K71MNOujR_tKcqLA6Qmp3v4ATNE_a5q_RM,1078
+phonipy-0.1.0.dist-info/RECORD,,

phonipy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

phonipy-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+phonipy = phonipy.cli:main

phonipy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Umair Danish
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE 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.