modusa 0.2.22__py3-none-any.whl → 0.3__py3-none-any.whl

modusa/tools/audio_loader.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+
+
+import soundfile as sf
+from scipy.signal import resample
+from pathlib import Path
+import tempfile
+from scipy.signal import resample
+from .youtube_downloader import download
+from .audio_converter import convert
+
+
+def load(path, sr=None):
+	"""
+	Loads audio file from various sources.
+
+	.. code-block:: python
+		
+		import modusa as ms
+		audio_fp = ms.load(
+			"https://www.youtube.com/watch?v=lIpw9-Y_N0g",
+			sr = None)
+
+	Parameters
+	----------
+	path: str
+		- Path to the audio
+		- Youtube URL
+	sr: int
+		- Sampling rate to load the audio in.
+
+	Return
+	------
+	np.ndarray
+		- Audio signal.
+	int
+		- Sampling rate of the loaded audio signal.
+	title
+		- Title of the loaded audio.
+		- Filename without extension or YouTube title.
+	"""
+	
+	# Check if the path is YouTube
+	if ".youtube." in str(path):
+		# Download the audio in temp directory using tempfile module
+		with tempfile.TemporaryDirectory() as tmpdir:
+			# Download
+			audio_fp: Path = download(url=path, content_type="audio", output_dir=Path(tmpdir))
+			
+			# Convert the audio to ".wav" form for loading
+			wav_audio_fp: Path = convert(inp_audio_fp=audio_fp, output_audio_fp=audio_fp.with_suffix(".wav"))
+			
+			# Load the audio in memory
+			audio_data, audio_sr = sf.read(wav_audio_fp)
+			title = audio_fp.stem
+			
+			# Convert to mono if it's multi-channel
+			if audio_data.ndim > 1:
+				audio_data = audio_data.mean(axis=1)
+				
+			# Resample if needed
+			if sr is not None:
+				if audio_sr != sr:
+					n_samples = int(len(audio_data) * sr / audio_sr)
+					audio_data = resample(audio_data, n_samples)
+					audio_sr = sr
+		
+	else:
+		# Check if the file exists
+		fp = Path(path)
+		
+		if not fp.exists():
+			raise FileNotFoundError(f"{path} does not exist.")
+		
+		# Load the audio in memory
+		audio_data, audio_sr = sf.read(fp)
+		title = fp.stem
+		
+		# Convert to mono if it's multi-channel
+		if audio_data.ndim > 1:
+			audio_data = audio_data.mean(axis=1)
+			
+		# Resample if needed
+		if sr is not None:
+			if audio_sr != sr:
+				n_samples = int(len(audio_data) * sr / audio_sr)
+				audio_data = resample(audio_data, n_samples)
+				audio_sr = sr
+	
+	return audio_data, audio_sr, title

modusa/tools/audio_player.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+
+import numpy as np
+from IPython.display import display, HTML, Audio
+
+def play(y: np.ndarray, sr: float, t0: float = 0.0, regions = None, title = None) -> None:
+		"""
+		Plays audio clips for given regions in Jupyter Notebooks.
+
+		Parameters
+		----------
+		y : np.ndarray
+			- Audio data.
+			- Mono (1D) numpy array.
+		sr: float
+			- Sampling rate of the audio.
+		t0: float
+			- Starting timestamp, incase the audio is cropped
+			- Default: 0.0 → Starts from 0.0 sec
+		regions : list[tuple[float, float, str]] | tuple[float, float, str] | None
+			- Regions to extract and play (in sec), e.g. [(0, 10.2, "tag")]
+			- If there is only one region, a tuple should also work. e.g. (0, 10.2, "tag")
+			- Default: None → The entire song is selected.
+		title : str | None
+			- Title to display above audio players.
+
+		Returns
+		-------
+		None
+		"""
+		if title:
+			display(HTML(f"<h4>{title}</h4>"))
+			
+		clip_tags = []
+		timings = []
+		players = []
+	
+		if isinstance(regions, tuple): regions = [regions] # (10, 20, "Region 1") -> [(10, 20, "Region 1")]
+	
+		if regions is not None:
+			for region in regions:
+				assert len(region) == 3
+				
+				start_sec = region[0] - t0
+				end_sec = region[1] - t0
+				tag = region[2]
+				
+				start_sample, end_sample = int(start_sec * sr), int(end_sec * sr)
+				clip = y[start_sample: end_sample]
+				audio_player = Audio(data=clip, rate=sr)._repr_html_()
+				
+				clip_tags.append(f"<td style='text-align:center; border-right:1px solid #ccc; padding:6px;'>{tag}</td>")
+				timings.append(f"<td style='text-align:center; border-right:1px solid #ccc; padding:6px;'>{start_sec:.2f}s → {end_sec:.2f}s</td>")
+				players.append(f"<td style='padding:6px;'>{audio_player}</td>")
+		else:
+			audio_player = Audio(data=y, rate=sr)._repr_html_()
+			
+			start_sec = t0
+			end_sec = t0 + y.shape[0] / sr
+			
+			clip_tags.append(f"<td style='text-align:center; border-right:1px solid #ccc; padding:6px;'>1</td>")
+			timings.append(f"<td style='text-align:center; border-right:1px solid #ccc; padding:6px;'>{start_sec:.2f}s → {end_sec:.2f}s</td>")
+			players.append(f"<td style='padding:6px;'>{audio_player}</td>")
+			
+		# Wrap rows in a table with border
+		table_html = f"""
+		<div style="display:inline-block; border:1px solid #ccc; border-radius:6px; overflow:hidden;">
+			<table style="border-collapse:collapse;">
+				<tr style="background-color:#f2f2f2;">
+					<th style="text-align:left; padding:6px 12px;">Clip</th>
+					{''.join(clip_tags)}
+				</tr>
+				<tr style="background-color:#fcfcfc;">
+					<th style="text-align:left; padding:6px 12px;">Timing</th>
+					{''.join(timings)}
+				</tr>
+				<tr>
+					<th style="text-align:left; padding:6px 12px;">Player</th>
+					{''.join(players)}
+				</tr>
+			</table>
+		</div>
+		"""
+	
+		return HTML(table_html)
+
+		
+		
+		

modusa/tools/base.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+
+from abc import ABC, abstractmethod
+
+class ModusaTool(ABC):
+	"""
+	Base class for all tool: youtube downloader, audio converter, filter.
+	
+	>>> modusa-dev create io
+
+	.. code-block:: python
+		
+		# General template of a subclass of ModusaTool
+		from modusa.tools.base import ModusaTool
+
+		class MyCustomIOClass(ModusaIO):
+			#--------Meta Information----------
+			_name = "My Custom Tool"
+			_description = "My custom class for Tool."
+			_author_name = "Ankit Anand"
+			_author_email = "ankit0.anand0@gmail.com"
+			_created_at = "2025-07-06"
+			#----------------------------------
+			
+			@staticmethod
+			def do_something():
+				pass
+		
+	
+	Note
+	----
+	- This class is intended to be subclassed by any tool built for the modusa framework.
+	- In order to create a tool, you can use modusa-dev CLI to generate a template.
+	- It is recommended to treat subclasses of ModusaTool as namespaces and define @staticmethods with control parameters, rather than using instance-level __init__ methods.
+	"""
+	
+	#--------Meta Information----------
+	_name: str = "Modusa Tool"
+	_description: str = "Base class for any tool in the Modusa framework."
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-11"
+	#----------------------------------

modusa/tools/math_ops.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+
+from modusa import excp
+from modusa.tools.base import ModusaTool
+from typing import Any
+import numpy as np
+
+class MathOps(ModusaTool):
+	"""
+	Performs arithmetic and NumPy-style ops.
+
+	Note
+	----
+	- Shape-changing operations like reshape, transpose, etc. are not yet supported. Use only element-wise or aggregation ops for now. 
+	- Index alignment must be handled carefully in future extensions.
+	"""
+	
+	def _axes_match(a1: tuple[np.ndarray, ...], a2: tuple[np.ndarray, ...]) -> bool:
+		"""
+		To check if two axes are same.
+
+		It checks the length of the axes and the corresponding values.
+		"""
+		if len(a1) != len(a2):
+			return False
+		return all(np.allclose(x, y, atol=1e-8) for x, y in zip(a1, a2))
+	
+	
+	#----------------------------------
+	# To handle basic element wise 
+	# math operations like
+	# +, -, *, **, / ...
+	#----------------------------------
+	
+	@staticmethod
+	def add(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.add(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be added") from e
+			
+		if isinstance(a, str) and isinstance(b, str): # numpy actually concatenates, we do not want that
+			raise excp.InputError(f"`a` and `b` can't be added")
+		return result
+	
+	@staticmethod
+	def subtract(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.subtract(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be subtracted") from e
+		return result
+		
+	@staticmethod
+	def multiply(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.multiply(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be multiplied") from e
+		
+		if isinstance(a, str) and isinstance(b, str): # numpy actually concatenates, we do not want that
+			raise excp.InputError(f"`a` and `b` can't be multiplied")
+		return result
+
+	@staticmethod
+	def divide(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.divide(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be divided") from e
+		return result
+
+	@staticmethod
+	def power(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.power(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` can't be exponentiated with `b`") from e
+		return result
+	
+	@staticmethod
+	def floor_divide(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.floor_divide(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` can't be floor divided by `b`") from e
+		return result
+		
+	#----------------------------------
+	# To handle numpy aggregator ops
+	#----------------------------------
+	@staticmethod
+	def mean(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		try:
+			result = np.mean(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find mean for `a`") from e
+		return result
+	
+	@staticmethod
+	def std(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		""""""
+		try:
+			result = np.std(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find std for `a`") from e
+		return result
+	
+	@staticmethod
+	def min(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		try:
+			result = np.min(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find min for `a`") from e
+		return result
+	
+	@staticmethod
+	def max(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		try:
+			result = np.max(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find max for `a`") from e
+		return result
+	
+	@staticmethod
+	def sum(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		try:
+			result = np.sum(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find sum for `a`") from e
+		return result
+	
+	#----------------------------------
+	# To handle numpy ops where the
+	# shapes are unaltered
+	# sin, cos, exp, log, ...
+	#----------------------------------
+	
+	@staticmethod
+	def sin(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.sin(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find sin for `a`") from e
+		return result
+	
+	@staticmethod
+	def cos(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.cos(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find cos for `a`") from e
+		return result
+	
+	@staticmethod
+	def tanh(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.tanh(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find tanh for `a`") from e
+		return result
+	
+	@staticmethod
+	def exp(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.exp(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find exp for `a`") from e
+		return result
+	
+	@staticmethod
+	def log(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.log(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find log for `a`") from e
+		return result
+	
+	@staticmethod
+	def log10(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.log10(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find log10 for `a`") from e
+		return result
+	
+	@staticmethod
+	def log2(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.log2(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find log2 for `a`") from e
+		return result
+	
+	@staticmethod
+	def log1p(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.log1p(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find log1p for `a`") from e
+		return result
+	
+	
+	@staticmethod
+	def sqrt(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.sqrt(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find sqrt for `a`") from e
+		return result
+	
+	@staticmethod
+	def abs(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.abs(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find abs for `a`") from e
+		return result
+	
+	@staticmethod
+	def floor(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.floor(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find floor for `a`") from e
+		return result
+	
+	@staticmethod
+	def ceil(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.ceil(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find ceil for `a`") from e
+		return result
+	
+	@staticmethod
+	def round(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.round(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find round for `a`") from e
+		return result
+	
+	#------------------------------------
+	# TODO: Add shape-changing ops like 
+	# reshape, transpose, squeeze later
+	#------------------------------------
+	
+	@staticmethod
+	def reshape(a: Any, shape: int | tuple[int, ...]) -> np.ndarray:
+		try:
+			result = np.reshape(a, shape=shape)
+		except Exception as e:
+			raise excp.InputError(f"can't reshape `a`") from e
+		return result
+	
+	#------------------------------------
+	# Complex numbers operations
+	#------------------------------------
+	
+	@staticmethod
+	def real(a: Any) -> np.ndarray:
+		try:
+			result = np.real(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find real for `a`") from e
+		return result
+	
+	@staticmethod
+	def imag(a: Any) -> np.ndarray:
+		try:
+			result = np.imag(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find imag for `a`") from e
+		return result
+	
+	@staticmethod
+	def angle(a: Any) -> np.ndarray:
+		try:
+			result = np.angle(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find angle for `a`") from e
+		return result
+	
+	#------------------------------------
+	# Comparison
+	#------------------------------------
+	
+	@staticmethod
+	def lt(a: Any, b: Any) -> np.ndarray:
+		try:
+			mask = a < b
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be compared") from e
+		return mask
+	
+	@staticmethod
+	def le(a: Any, b: Any) -> np.ndarray:
+		try:
+			mask = a <= b
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be compared") from e
+		return mask
+	
+	@staticmethod
+	def gt(a: Any, b: Any) -> np.ndarray:
+		try:
+			mask = a > b
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be compared") from e
+		return mask
+	
+	@staticmethod
+	def ge(a: Any, b: Any) -> np.ndarray:
+		try:
+			mask = a >= b
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be compared") from e
+		return mask
+	
+	@staticmethod
+	def eq(a: Any, b: Any) -> np.ndarray:
+		try:
+			mask = a == b
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be compared") from e
+		return mask
+	
+	@staticmethod
+	def ne(a: Any, b: Any) -> np.ndarray:
+		try:
+			mask = a != b
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be compared") from e
+		return mask