pyspectools2 1.0.2__tar.gz

pyspectools2-1.0.2/.gitignore

@@ -0,0 +1,162 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

pyspectools2-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [Your Name]
+
+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.

pyspectools2-1.0.2/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: pyspectools2
+Version: 1.0.2
+Summary: A library for recording and plotting spectrograms from audio data.
+Author-email: "Sviatoslav Z." <slawekzhukovski@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: sounddevice
+Description-Content-Type: text/markdown
+
+# Spectrogram Recorder Library
+
+A Python library for recording audio, generating spectrograms, and managing session data.
+
+## Features
+
+- Record audio from your default input device (`sounddevice`).
+- Plot and save spectrograms (`matplotlib`).
+- Create numbered session folders (`session_1`, `session_2`, ...).
+- Delete the latest session and inspect folder sizes.
+- Cross-platform default save location based on the current user's home directory.
+
+## Installation
+
+```bash
+pip install py-spectrogram-tools
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/Ampter/py-spectrogram-tools
+cd py-spectrogram-tools
+pip install .
+```
+
+## Dependencies
+
+- numpy
+- sounddevice
+- matplotlib
+
+## Import
+
+```python
+import pyspectools as pst
+```
+
+## API
+
+### `pst.get_default_directory()`
+Returns the default directory for spectrogram sessions:
+
+- Windows: `C:\Users\<username>\SOUNDS\spectrograms`
+- macOS: `/Users/<username>/SOUNDS/spectrograms`
+- Linux: `/home/<username>/SOUNDS/spectrograms`
+
+### `pst.create_session_folder(directory=None)`
+Creates a new folder such as `session_5` and returns its path.
+
+### `pst.get_latest_session_folder(directory=None)`
+Returns the highest numbered session folder path, or `None`.
+
+### `pst.record_audio(duration=3, rate=44100, channels=1)`
+Records audio and returns a flattened NumPy array.
+
+### `pst.plot_spectrogram(audio_data, rate=44100)`
+Returns `(fig, ax)` for the generated spectrogram.
+
+### `pst.save_spectrogram(fig, session_folder)`
+Saves a PNG in the target session folder and returns the output file path.
+
+### `pst.delete_latest_session_folder(directory=None)`
+Deletes the latest session folder.
+
+### `pst.get_folder_size(directory=None)`
+Returns folder size in bytes.
+
+### `pst.print_folder_size(directory=None)`
+Prints the total size of the latest session folder.
+
+## Usage Example
+
+```python
+import pyspectools as pst
+
+session_folder = pst.create_session_folder()
+audio_data = pst.record_audio(duration=5)
+fig, _ = pst.plot_spectrogram(audio_data)
+output_file = pst.save_spectrogram(fig, session_folder)
+
+print(f"Saved spectrogram: {output_file}")
+```
+
+## Contributing
+
+Contributions are welcome.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.

pyspectools2-1.0.2/README.md

@@ -0,0 +1,91 @@
+# Spectrogram Recorder Library
+
+A Python library for recording audio, generating spectrograms, and managing session data.
+
+## Features
+
+- Record audio from your default input device (`sounddevice`).
+- Plot and save spectrograms (`matplotlib`).
+- Create numbered session folders (`session_1`, `session_2`, ...).
+- Delete the latest session and inspect folder sizes.
+- Cross-platform default save location based on the current user's home directory.
+
+## Installation
+
+```bash
+pip install py-spectrogram-tools
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/Ampter/py-spectrogram-tools
+cd py-spectrogram-tools
+pip install .
+```
+
+## Dependencies
+
+- numpy
+- sounddevice
+- matplotlib
+
+## Import
+
+```python
+import pyspectools as pst
+```
+
+## API
+
+### `pst.get_default_directory()`
+Returns the default directory for spectrogram sessions:
+
+- Windows: `C:\Users\<username>\SOUNDS\spectrograms`
+- macOS: `/Users/<username>/SOUNDS/spectrograms`
+- Linux: `/home/<username>/SOUNDS/spectrograms`
+
+### `pst.create_session_folder(directory=None)`
+Creates a new folder such as `session_5` and returns its path.
+
+### `pst.get_latest_session_folder(directory=None)`
+Returns the highest numbered session folder path, or `None`.
+
+### `pst.record_audio(duration=3, rate=44100, channels=1)`
+Records audio and returns a flattened NumPy array.
+
+### `pst.plot_spectrogram(audio_data, rate=44100)`
+Returns `(fig, ax)` for the generated spectrogram.
+
+### `pst.save_spectrogram(fig, session_folder)`
+Saves a PNG in the target session folder and returns the output file path.
+
+### `pst.delete_latest_session_folder(directory=None)`
+Deletes the latest session folder.
+
+### `pst.get_folder_size(directory=None)`
+Returns folder size in bytes.
+
+### `pst.print_folder_size(directory=None)`
+Prints the total size of the latest session folder.
+
+## Usage Example
+
+```python
+import pyspectools as pst
+
+session_folder = pst.create_session_folder()
+audio_data = pst.record_audio(duration=5)
+fig, _ = pst.plot_spectrogram(audio_data)
+output_file = pst.save_spectrogram(fig, session_folder)
+
+print(f"Saved spectrogram: {output_file}")
+```
+
+## Contributing
+
+Contributions are welcome.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.

pyspectools2-1.0.2/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyspectools2"
+dynamic = ["version"]
+description = "A library for recording and plotting spectrograms from audio data."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Sviatoslav Z.", email = "slawekzhukovski@gmail.com" },
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "matplotlib",
+    "numpy",
+    "sounddevice",
+]
+
+[tool.hatch.version]
+path = "pyspectools2/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/pyspectools2",
+]

pyspectools2-1.0.2/pyspectools2/__init__.py

@@ -0,0 +1,27 @@
+"""Public package API for py-spectrogram-tools."""
+
+__version__ = "1.0.2"
+
+from .spectrogram import (
+    create_session_folder,
+    delete_latest_session_folder,
+    get_default_directory,
+    get_folder_size,
+    get_latest_session_folder,
+    plot_spectrogram,
+    print_folder_size,
+    record_audio,
+    save_spectrogram,
+)
+
+__all__ = [
+    "create_session_folder",
+    "delete_latest_session_folder",
+    "get_default_directory",
+    "get_folder_size",
+    "get_latest_session_folder",
+    "plot_spectrogram",
+    "print_folder_size",
+    "record_audio",
+    "save_spectrogram",
+]

pyspectools2-1.0.2/pyspectools2/spectrogram.py

@@ -0,0 +1,146 @@
+import os
+import platform
+import re
+import shutil
+import time
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import sounddevice as sd
+
+_SESSION_PATTERN = re.compile(r"^session_(\d+)$")
+
+
+def get_default_directory() -> str:
+    """Return the default directory based on the operating system."""
+    system = platform.system().lower()
+    home_dir = Path.home()
+
+    if system in {"windows", "darwin", "linux"}:
+        return str(home_dir / "SOUNDS" / "spectrograms")
+
+    raise OSError("Unsupported operating system")
+
+
+def _get_session_numbers(directory: str) -> list[int]:
+    """Collect valid session numbers from directory entries."""
+    session_numbers: list[int] = []
+    for entry in os.listdir(directory):
+        full_path = os.path.join(directory, entry)
+        if not os.path.isdir(full_path):
+            continue
+
+        match = _SESSION_PATTERN.match(entry)
+        if match:
+            session_numbers.append(int(match.group(1)))
+
+    return session_numbers
+
+
+def create_session_folder(directory=None) -> str:
+    """Create a new session folder inside the provided directory."""
+    if directory is None:
+        directory = get_default_directory()
+
+    os.makedirs(directory, exist_ok=True)
+
+    next_number = max(_get_session_numbers(directory), default=0) + 1
+    while True:
+        session_folder = os.path.join(directory, f"session_{next_number}")
+        try:
+            os.makedirs(session_folder, exist_ok=False)
+            print(f"Created new session: {session_folder}")
+            return session_folder
+        except FileExistsError:
+            next_number += 1
+
+
+def get_latest_session_folder(directory=None) -> str | None:
+    """Find the session folder with the highest number and return its path."""
+    if directory is None:
+        directory = get_default_directory()
+
+    if not os.path.exists(directory):
+        return None
+
+    session_numbers = _get_session_numbers(directory)
+    if not session_numbers:
+        return None
+
+    latest_session = max(session_numbers)
+    return os.path.join(directory, f"session_{latest_session}")
+
+
+def plot_spectrogram(audio_data, rate=44100) -> tuple:
+    """Plot the spectrogram of the given audio data."""
+    fig, ax = plt.subplots()
+    ax.set_title("Spectrogram")
+    ax.set_xlabel("Time (s)")
+    ax.set_ylabel("Frequency (Hz)")
+    ax.specgram(audio_data, NFFT=256, Fs=rate, noverlap=128)
+    return fig, ax
+
+
+def save_spectrogram(fig, session_folder) -> str:
+    """Save the generated spectrogram plot to the session folder."""
+    timestamp = time.ctime().replace(" ", "_").replace(":", "-")
+    filename = os.path.join(session_folder, f"spectrogram_{timestamp}.png")
+    fig.savefig(filename)
+    plt.close(fig)
+    return filename
+
+
+def record_audio(duration=3, rate=44100, channels=1):
+    """Record audio data and return it as a flattened array."""
+    print("Starting recording...")
+    audio_data = sd.rec(int(rate * duration),
+                        samplerate=rate, channels=channels)
+    sd.wait()
+    print("Recording finished.")
+    return audio_data.flatten()
+
+
+def delete_latest_session_folder(directory=None):
+    """Delete the latest session folder."""
+    if directory is None:
+        directory = get_default_directory()
+
+    latest_session_folder = get_latest_session_folder(directory)
+    if latest_session_folder is None:
+        print("No session folders found to delete.")
+        return
+
+    try:
+        shutil.rmtree(latest_session_folder)
+        print(f"Deleted the latest session folder: {latest_session_folder}")
+    except Exception as exc:
+        print(f"Error deleting the folder: {exc}")
+
+
+def get_folder_size(directory=None):
+    """Calculate the total size of a directory."""
+    if directory is None:
+        directory = get_default_directory()
+
+    total_size = 0
+    for dirpath, _, filenames in os.walk(directory):
+        for filename in filenames:
+            file_path = os.path.join(dirpath, filename)
+            total_size += os.path.getsize(file_path)
+    return total_size
+
+
+def print_folder_size(directory=None):
+    """Print the total size of the latest session folder."""
+    if directory is None:
+        directory = get_default_directory()
+
+    latest_session_folder = get_latest_session_folder(directory)
+    if latest_session_folder is None:
+        print("No session folder found.")
+        return
+
+    total_size = get_folder_size(latest_session_folder)
+    print(
+        f"Total size of folder {latest_session_folder}: {total_size / (1024 * 1024):.2f} MB"
+    )