modusa 0.4.29__tar.gz → 0.4.31__tar.gz

{modusa-0.4.29 → modusa-0.4.31}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: modusa
-Version: 0.4.29
+Version: 0.4.31
 Summary: A modular signal analysis python library.
 Author-Email: Ankit Anand <ankit0.anand0@gmail.com>
 License: MIT
 Requires-Python: >=3.11
 Requires-Dist: numpy>=2.2.6
 Requires-Dist: matplotlib>=3.10.3
-Requires-Dist: yt-dlp==2025.9.23
+Requires-Dist: yt-dlp==2025.10.22
 Requires-Dist: IPython>=9.5.0
 Requires-Dist: sounddevice>=0.5.2
 Requires-Dist: ipywidgets>=8.1.7

{modusa-0.4.29 → modusa-0.4.31}/pyproject.toml

@@ -8,7 +8,7 @@ authors = [
 dependencies = [
     "numpy>=2.2.6",
     "matplotlib>=3.10.3",
-    "yt-dlp==2025.9.23",
+    "yt-dlp==2025.10.22",
     "IPython>=9.5.0",
     "sounddevice>=0.5.2",
     "ipywidgets>=8.1.7",
@@ -16,7 +16,7 @@ dependencies = [
 ]
 requires-python = ">=3.11"
 readme = "README.md"
-version = "0.4.29"
+version = "0.4.31"
 
 [project.license]
 text = "MIT"

modusa-0.4.31/src/modusa/__init__.py

@@ -0,0 +1,17 @@
+# Audio related
+from modusa.tools import load, play, convert, record
+from modusa.tools import download
+
+# Annotation related
+from modusa.tools import load_ann, save_ann
+
+# Plotting related
+from modusa.tools import dist_plot, hill_plot, plot, fig
+
+# Synthsizing related
+from modusa.tools import synth_f0
+
+# Audio features related
+from modusa.tools import stft
+
+__version__ = "0.4.31" # This is dynamically used by the documentation, and pyproject.toml; Only need to change it here; rest gets taken care of.

{modusa-0.4.29 → modusa-0.4.31}/src/modusa/tools/__init__.py

@@ -1,14 +1,22 @@
 #!/usr/bin/env python3
 
+# Audio related
 from .audio_player import play
 from .audio_converter import convert
 from .youtube_downloader import download
 from .audio_loader import load
-from .audio_saver import save
-from .ann_loader import load_ann
 from .audio_recorder import record
 
+# Annotation related
+from .ann_loader import load_ann
+from .ann_saver import save_ann
+
+# Plotting related
 from .plotter import Fig as fig
 from .plotter import dist_plot, hill_plot, plot
 
-from .synth import synth_f0
+# Synthesizing related
+from .synth import synth_f0
+
+# Audio features
+from .audio_stft import stft

modusa-0.4.31/src/modusa/tools/ann_saver.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+
+#---------------------------------
+# Author: Ankit Anand
+# Date: 23/10/25
+# Email: ankit0.anand0@gmail.com
+#---------------------------------
+
+from pathlib import Path
+
+def save_ann(ann, output_fp):
+	"""
+	Saves annotation as a text file.
+	It can be opened in audacity for inspection.
+
+	Paramters
+	---------
+	ann: list[tuple[float, float, str]]
+		- List of (start, end, label).
+	output_fp: str
+		- Filepath to save the annotation.
+	"""
+	
+	output_fp = Path(output_fp)
+	output_fp.parent.mkdir(parents=True, exist_ok=True)
+	
+	with open(output_fp, "w") as f:
+		for (s, e, label) in ann:
+			f.write(f"{s:.6f}\t{e:.6f}\t{label}\n")
+	

{modusa-0.4.29 → modusa-0.4.31}/src/modusa/tools/audio_recorder.py

@@ -6,7 +6,6 @@
 # Email: ankit0.anand0@gmail.com
 #---------------------------------
 
-
 import sounddevice as sd
 import numpy as np
 import ipywidgets as widgets

modusa-0.4.31/src/modusa/tools/audio_stft.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+
+#---------------------------------
+# Author: Ankit Anand
+# Date: 23/10/25
+# Email: ankit0.anand0@gmail.com
+#---------------------------------
+
+import numpy as np
+
+def stft(y, sr, winlen=None, hoplen=None, gamma=None):
+	"""
+	Compute spectrogram with just numpy.
+
+	Parameters
+	----------
+	y: ndarray
+		- Audio signal.
+	sr: int
+		- Sampling rate of the audio signal.
+	winlen: int
+		- Window length in samples.
+		- Default: None => set at 0.064 sec
+	hoplen: int
+		- Hop length in samples.
+		- Default: None => set at one-forth of winlen
+	gamma: int | None
+		- Log compression factor.
+		- Add contrast to the plot.
+
+	Returns
+	-------
+	ndarray:
+		- Spectrogram matrix, complex is gamma is None else real
+	ndarray:
+		- Frequency bins in Hz.
+	ndarray:
+		- Timeframes in sec.
+	"""
+	
+	if winlen is None:
+		winlen = 2 ** int(np.log2(0.064 * sr))
+	if hoplen is None:
+		hoplen = int(winlen * 0.25)
+		
+	# Estimating the shape of the S matrix
+	M = int(np.ceil(winlen / 2))
+	N = int(np.ceil((y.size - winlen) / hoplen))
+	
+	# Initialize the S matrix
+	S = np.empty((M, N), dtype=np.complex64) # M X N => freq bin X time frame
+	
+	# We will need a hann window
+	hann = np.hanning(winlen)
+	
+	# Get the frames
+	frames = np.lib.stride_tricks.sliding_window_view(y, window_shape=winlen)[::hoplen] # frame X chunk
+	
+	# Apply window to the frame
+	frames_windowed = frames * hann # frame X chunk
+	
+	# Compute fft for each frame
+	S = np.fft.rfft(frames_windowed, n=winlen, axis=1).T  # transpose to match shape (freq_bins, frame)
+	
+	# Magnitude spectrogram
+	Sf = np.fft.rfftfreq(winlen, d=1/sr) # Frequency bins (Hz)
+	St = np.arange(N) * hoplen / sr # Time bins (sec)
+	
+	if gamma is not None:
+		S = np.log1p(gamma * np.abs(S))
+		
+	return S, Sf, St

{modusa-0.4.29 → modusa-0.4.31}/src/modusa/tools/youtube_downloader.py

@@ -1,9 +1,6 @@
 #!/usr/bin/env python3
 
 
-from modusa import excp
-from modusa.decorators import validate_args_type
-from modusa.tools.base import ModusaTool
 from typing import Any
 from pathlib import Path
 import yt_dlp
@@ -66,7 +63,7 @@ def download(url, content_type, output_dir):
 			info = ydl.extract_info(url, download=True)
 			return Path(info['requested_downloads'][0]['filepath'])
 	else:
-		raise excp.InputValueError(f"`content_type` can either take 'audio' or 'video' not {content_type}")
+		raise ValueError(f"`content_type` can either take 'audio' or 'video' not {content_type}")
 
 	
 	

modusa-0.4.29/src/modusa/__init__.py

@@ -1,13 +0,0 @@
-from modusa.utils import excp, config
-
-#=====Giving access to plot functions to plot multiple signals.=====
-from modusa.tools import dist_plot, hill_plot, plot, fig
-#=====
-
-from modusa.tools import play, convert, record, save
-from modusa.tools import download
-from modusa.tools import load, load_ann
-
-from modusa.tools import synth_f0
-
-__version__ = "0.4.29"

modusa-0.4.29/src/modusa/config.py

@@ -1,18 +0,0 @@
-#!/usr/bin/env python3
-
-import logging
-
-class Config:
-	LOG_LEVEL = logging.WARNING
-	SR = 44100  # Default sampling rate
-	TIME_UNIT = "sec"
-	
-	
-	def __str__(self):
-		return self.__dict__
-	
-	def __repr__(self):
-		return self.__dict__
-
-# Create a singleton instance
-config = Config()

modusa-0.4.29/src/modusa/decorators.py

@@ -1,176 +0,0 @@
-#!/usr/bin/env python3
-
-from modusa import excp
-from functools import wraps
-from typing import Any, Callable, Type
-from inspect import signature, Parameter
-from typing import get_origin, get_args, Union
-import types
-
-
-#----------------------------------------------------
-# Safety check for plugin (apply method)
-# Check if the input type, output type is allowed,
-# Also logs plugin usage.
-#----------------------------------------------------
-def plugin_safety_check(
-	validate_plugin_input: bool = True,
-	validate_plugin_output: bool = True,
-	track_plugin_usage: bool = True
-):
-	def decorator(func: Callable) -> Callable:
-		@wraps(func)
-		def wrapper(self, signal: Any, *args, **kwargs):
-			
-			if validate_plugin_input:
-				if not hasattr(self, 'allowed_input_signal_types'):
-					raise excp.AttributeNotFoundError(f"{self.__class__.__name__} must define `allowed_input_signal_types`.")
-				
-				if type(signal) not in self.allowed_input_signal_types:
-					raise excp.PluginInputError(f"{self.__class__.__name__} must take input signal of type {self.allowed_input_signal_types} but got {type(signal)}")
-			
-			if track_plugin_usage:
-				if not hasattr(signal, '_plugin_chain'):
-					raise excp.AttributeNotFoundError(f"Signal of type {type(signal).__name__} must have a `_plugin_chain` attribute for plugin tracking.")
-					
-				if not isinstance(signal._plugin_chain, list):
-					raise excp.TypeError(f"`_plugin_chain` must be a list, but got {type(signal._plugin_chain)}")
-					
-				signal._plugin_chain.append(self.__class__.__name__)
-			
-			result = func(self, signal, *args, **kwargs)
-			
-			if validate_plugin_output:
-				if not hasattr(self, 'allowed_output_signal_types'):
-					raise excp.AttributeNotFoundError(f"{self.__class__.__name__} must define `allowed_output_signal_types`.")
-				if type(result) not in self.allowed_output_signal_types:
-					raise excp.PluginInputError(f"{self.__class__.__name__} must return output of type {self.allowed_output_signal_types} but returned {type(result)}")
-			return result
-	
-		return wrapper
-	return decorator
-
-
-#----------------------------------------------------
-# Safety check for generators (generate method)
-# Check if the ouput type is allowed.
-#----------------------------------------------------
-def generator_safety_check():
-	"""
-	We assume that the first argument is self, so that we can actually extract properties to
-	validate.
-	"""
-	def decorator(func: Callable) -> Callable:
-		@wraps(func)
-		def wrapper(self, *args, **kwargs):
-			result = func(self, *args, **kwargs)
-			
-			if not hasattr(self, 'allowed_output_signal_types'):
-				raise excp.AttributeNotFoundError(
-					f"{self.__class__.__name__} must define `allowed_output_signal_types`."
-				)
-			if type(result) not in self.allowed_output_signal_types:
-				raise excp.PluginInputError(
-					f"{self.__class__.__name__} must return output of type {self.allowed_output_signal_types}, "
-					f"but returned {type(result)}"
-				)
-				
-			return result
-		return wrapper
-	return decorator
-
-
-#----------------------------------------------------
-# Validation for args type
-# When this decorator is added to a function, it
-# automatically checks all the arguments with their
-# expected types. (self, forward type references are
-# ignored)
-#----------------------------------------------------
-
-def validate_arg(arg_name: str, value: Any, expected_type: Any) -> None:
-	"""
-	Checks if `value_type` matches `expected_type`.
-	Raises TypeError if not.
-	"""
-	import types
-	from typing import get_origin, get_args, Union
-	
-	origin = get_origin(expected_type)
-	
-	# Handle Union (e.g. int | None)
-	if origin in (Union, types.UnionType):
-		union_args = get_args(expected_type)
-		for typ in union_args:
-			typ_origin = get_origin(typ) or typ
-			if isinstance(value, typ_origin):
-				return
-		
-		# ❌ If none match
-		expected_names = ", ".join(
-			get_origin(t).__name__ if get_origin(t) else t.__name__ for t in union_args
-		)
-		raise excp.InputTypeError(
-			f"Argument '{arg_name}' must be one of ({expected_names}), got {type(value).__name__}"
-		)
-	
-	# Handle generic types like list[float], tuple[int, str]
-	elif origin is not None:
-		if not isinstance(value, origin):
-			raise excp.InputTypeError(
-				f"Argument '{arg_name}' must be of type {origin.__name__}, got {type(value).__name__}"
-			)
-		return
-		
-	# ✅ Handle plain types
-	elif isinstance(expected_type, type):
-		if not isinstance(value, expected_type):
-			raise excp.InputTypeError(
-				f"Argument '{arg_name}' must be of type {expected_type.__name__}, got {type(value).__name__}"
-			)
-		return
-	# ❌ Unsupported type structure
-	else:
-		raise excp.InputTypeError(f"Unsupported annotation for '{arg_name}': {expected_type}")
-
-def validate_args_type() -> Callable:
-	def decorator(func: Callable) -> Callable:
-		@wraps(func)
-		def wrapper(*args, **kwargs):
-			sig = signature(func)
-			bound = sig.bind(*args, **kwargs)
-			bound.apply_defaults()
-			
-			for arg_name, value in bound.arguments.items():
-				param = sig.parameters[arg_name]
-				expected_type = param.annotation
-				
-				# Skip unannotated or special args
-				if expected_type is Parameter.empty or arg_name in ("self", "cls") or isinstance(expected_type, str):
-					continue
-				
-				validate_arg(arg_name, value, expected_type)  # <- this is assumed to be defined elsewhere
-				
-			return func(*args, **kwargs)
-		return wrapper
-	return decorator
-
-#-----------------------------------
-# Making a property immutable
-# and raising custom error message
-# during attempt to modify the values
-#-----------------------------------
-def immutable_property(error_msg: str):
-	"""
-	Returns a read-only property. Raises an error with a custom message on mutation.
-	"""
-	def decorator(getter):
-		name = getter.__name__
-		private_name = f"_{name}"
-		
-		def setter(self, value):
-			raise excp.ImmutableAttributeError(error_msg)
-			
-		return property(getter, setter)
-	
-	return decorator

modusa-0.4.29/src/modusa/devtools/generate_docs_source.py

@@ -1,92 +0,0 @@
-#!/usr/bin/env python3
-
-import inspect
-import importlib
-import pkgutil
-from pathlib import Path
-from collections import defaultdict
-
-# === Configuration ===
-BASE_MODULES = [
-    'modusa.tools',
-#   'modusa.models',
-#   'modusa.generators',
-#   'modusa.plugins',
-]
-OUTPUT_DIRS = [
-    Path('docs/source/tools'),
-#   Path('docs/source/models'),
-#   Path('docs/source/generators'),
-#   Path('docs/source/plugins'),
-]
-
-# Ensure output directories exist
-for output_dir in OUTPUT_DIRS:
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-# === Utils ===
-def get_classes_grouped_by_module(base_module):
-    """
-    Returns a dictionary: { module_path: [class_name, ...] }
-    """
-    found = defaultdict(list)
-    module = importlib.import_module(base_module)
-
-    for _, modname, _ in pkgutil.walk_packages(module.__path__, base_module + "."):
-        try:
-            submodule = importlib.import_module(modname)
-            for name, obj in inspect.getmembers(submodule, inspect.isclass):
-                if obj.__module__ == modname:
-                    found[modname].append(name)
-        except Exception as e:
-            print(f"⚠️ Skipping {modname} due to import error: {e}")
-    return found
-
-def write_module_rst_file(module_path, class_names, output_dir):
-    """
-    Writes a .rst file for a module, documenting all its classes.
-    Filename is based on the module, but title is the first class (Modusa* gets priority).
-    """
-    filename = output_dir / f"{module_path.split('.')[-1]}.rst"
-
-    # Prioritize 'Modusa*' classes first, then alphabetical
-    sorted_classes = sorted(class_names, key=lambda x: (not x.startswith("Modusa"), x.lower()))
-    title = sorted_classes[0] if sorted_classes else module_path.split('.')[-1]
-
-    with open(filename, 'w') as f:
-        f.write(f"{title}\n{'=' * len(title)}\n\n")
-        for class_name in sorted_classes:
-            f.write(f".. autoclass:: {module_path}.{class_name}\n")
-            f.write("   :members:\n")
-            f.write("   :undoc-members:\n")
-            f.write("   :show-inheritance:\n\n")
-    
-    return filename.name
-
-def write_index_rst_file(tools_by_module, output_dir, section_name="Tools"):
-    """
-    Writes index.rst in the given output_dir with 'base' on top, then other files alphabetically.
-    """
-    index_file = output_dir / "index.rst"
-    with open(index_file, "w") as f:
-        f.write(f"{section_name}\n{'=' * len(section_name)}\n\n")
-        f.write(".. toctree::\n   :maxdepth: 1\n\n")
-
-        filenames = [module_path.split('.')[-1] for module_path in tools_by_module]
-        sorted_filenames = sorted(filenames, key=lambda x: (x != "base", x.lower()))
-
-        for name in sorted_filenames:
-            f.write(f"   {name}\n")
-
-# === Main Script ===
-def generate_docs_source():
-    for base_module, output_dir in zip(BASE_MODULES, OUTPUT_DIRS):
-        module_class_map = get_classes_grouped_by_module(base_module)
-    
-        for module_path, class_list in module_class_map.items():
-            write_module_rst_file(module_path, class_list, output_dir)
-    
-        section_name = base_module.split('.')[-1].capitalize()
-    
-        write_index_rst_file(module_class_map, output_dir, section_name=section_name)
-        print(f"✅ Documentation generated for {base_module} in {output_dir}")

modusa-0.4.29/src/modusa/devtools/generate_template.py

@@ -1,144 +0,0 @@
-#!/usr/bin/env python3
-
-from datetime import date
-from pathlib import Path
-import questionary
-import sys
-
-ROOT_DIR = Path(__file__).parents[3].resolve()
-SRC_CODE_DIR = ROOT_DIR / "src/modusa"
-TESTS_DIR = ROOT_DIR / "tests"
-TEMPLATES_DIR = ROOT_DIR / "src/modusa/devtools/templates"
-
-PLUGIN_INFO = {
-	"template_fp": TEMPLATES_DIR / "plugin.py",
-	"test_template_fp": TEMPLATES_DIR / "test.py",
-	"template_dump_dp": SRC_CODE_DIR / "plugins",
-	"test_template_dump_dp": TESTS_DIR / "test_plugins"
-}
-IO_INFO = {
-	"template_fp": TEMPLATES_DIR / "io.py",
-	"test_template_fp": TEMPLATES_DIR / "test.py",
-	"template_dump_dp": SRC_CODE_DIR / "io",
-	"test_template_dump_dp": TESTS_DIR / "test_io"
-}
-GENERATOR_INFO = {
-	"template_fp": TEMPLATES_DIR / "generator.py",
-	"test_template_fp": TEMPLATES_DIR / "test.py",
-	"template_dump_dp": SRC_CODE_DIR / "generators",
-	"test_template_dump_dp": TESTS_DIR / "test_generators"
-}
-MODEL_INFO = {
-	"template_fp": TEMPLATES_DIR / "model.py",
-	"test_template_fp": TEMPLATES_DIR / "test.py",
-	"template_dump_dp": SRC_CODE_DIR / "models",
-	"test_template_dump_dp": TESTS_DIR / "test_models"
-}
-TOOL_INFO = {
-	"template_fp": TEMPLATES_DIR / "tool.py",
-	"test_template_fp": TEMPLATES_DIR / "test.py",
-	"template_dump_dp": SRC_CODE_DIR / "tools",
-	"test_template_dump_dp": TESTS_DIR / "test_tools"
-}
-
-
-class TemplateGenerator():
-	"""
-	Generates template for `plugin`, `engine`, `signal`, `generator` along with its corresponding `test` file
-	in the `tests` directory.
-	"""
-	
-	
-	@staticmethod
-	def get_path_info(for_what: str):
-		if for_what == "plugin": return PLUGIN_INFO
-		if for_what == "io": return IO_INFO
-		if for_what == "model": return MODEL_INFO
-		if for_what == "tool": return TOOL_INFO
-		if for_what == "generator": return GENERATOR_INFO
-	
-	@staticmethod
-	def ask_questions(for_what: str, path_info: dict) -> dict:
-		"""Asks question about the template to be generated."""
-		print("----------------------")
-		print(for_what.upper())
-		print("----------------------")
-		module_name = questionary.text("Module name (snake_case): ").ask()
-		
-		if module_name is None:
-			sys.exit(1)
-			
-		if not module_name.endswith(".py"): # Adding extension
-			module_name = module_name + ".py"
-		# Checking if the module name already exists in the dump directory
-		if (path_info["template_dump_dp"] / module_name).exists():
-			print(f"⚠️ File already exists, choose another name.")
-			sys.exit(1)
-		
-		class_name = questionary.text(f"Class name (CamelCase): ").ask()
-		if class_name is None:
-			sys.exit(1)
-			
-		author_name = questionary.text("Author name: ").ask()
-		if author_name is None:
-			sys.exit(1)
-		
-		author_email = questionary.text("Author email: ").ask()
-		if author_email is None:
-			sys.exit(1)
-		
-		answers = {"for_what": for_what, "module_name": module_name, "class_name": class_name, "author_name": author_name, "author_email": author_email, "date_created": date.today()}
-			
-		return answers
-	
-	@staticmethod
-	def load_template_file(template_fp: Path) -> str:
-		"""Loads template file."""
-		if not template_fp.exists():
-			print(f"❌ Template not found: {template_fp}")
-			sys.exit(1)
-		
-		template_code = template_fp.read_text()
-		
-		return template_code
-	
-	@staticmethod
-	def fill_placeholders(template_code: str, placehoders_dict: dict) -> str:
-		"""Fills placeholder in the template with the user input from CLI."""
-		template_code = template_code.format(**placehoders_dict)  # Fill placeholders
-		return template_code
-	
-	@staticmethod
-	def save_file(content: str, output_path: Path) -> None:
-		"""Saves file in the correct directory with the right tempalate content."""
-		output_path.parent.mkdir(parents=True, exist_ok=True)
-		output_path.write_text(content)
-		
-		# Generating a corresponding test file too
-		what_for = output_path.parent.name # plugins, generators, ...
-		module_name = output_path.name # this.py
-	
-	
-	@staticmethod
-	def create_template(for_what: str) -> None:
-		
-		# Load correct path location info for the templates and where to dump the files
-		path_info: dict = TemplateGenerator.get_path_info(for_what)
-		
-		# Ask basic questions to create the template for `plugin`, `generator`, ...
-		answers: dict = TemplateGenerator.ask_questions(for_what, path_info)
-		
-		# Load the correct template file and test file
-		template_code: str = TemplateGenerator.load_template_file(template_fp=path_info['template_fp'])
-		test_code: str = TemplateGenerator.load_template_file(template_fp=path_info['test_template_fp'])
-		
-		# Update the dynamic values based on the answers
-		template_code: str = TemplateGenerator.fill_placeholders(template_code, answers)
-		test_code: str = TemplateGenerator.fill_placeholders(test_code, answers)
-		
-		# Save it to a file and put it in the correct folder
-		TemplateGenerator.save_file(content=template_code, output_path=path_info['template_dump_dp'] / answers['module_name'])
-		TemplateGenerator.save_file(content=test_code, output_path=path_info['test_template_dump_dp'] / f"test_{answers['module_name']}")
-		
-		print(f"✅ {for_what}:", "open " + str(path_info['template_dump_dp'] / answers['module_name']))
-		print(f"✅ test:", "open " + str(path_info['test_template_dump_dp'] / f"test_{answers['module_name']}"))

modusa-0.4.29/src/modusa/devtools/list_authors.py

@@ -1,2 +0,0 @@
-#!/usr/bin/env python3
-