modusa 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

modusa/io/audio_converter.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.io.base import ModusaIO
+from typing import Any
+import subprocess
+from pathlib import Path
+
+
+class AudioConverter(ModusaIO):
+	"""
+	Converts audio using FFmpeg.
+
+	Note
+	----
+	- Use `convert()` to perform the actual format conversion.
+	- Requires FFMPEG to be installed on the system.
+	"""
+	
+	#--------Meta Information----------
+	_name = "Audio Converter"
+	_description = "Convert audio files using ffmpeg"
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-05"
+	#----------------------------------
+	
+	@staticmethod
+	@validate_args_type()
+	def convert(inp_audio_fp: str | Path, output_audio_fp: str | Path) -> Path:
+		"""
+		Converts an audio file from one format to another using FFmpeg.
+
+		.. code-block:: python
+			
+			from modusa.engines import AudioConverter
+			converted_audio_fp = AudioConverter.convert(
+				inp_audio_fp="path/to/input/audio.webm", 
+				output_audio_fp="path/to/output/audio.wav"
+			)
+
+		Parameters
+		----------
+		inp_audio_fp: str | Path
+			Filepath of audio to be converted.
+		output_audio_fp: str | Path
+			Filepath of the converted audio. (e.g. name.mp3)
+
+		Returns
+		-------
+		Path:
+			Filepath of the converted audio.
+
+		Note
+		----
+		- The conversion takes place based on the extensions of the input and output audio filepath.
+		"""
+		inp_audio_fp = Path(inp_audio_fp)
+		output_audio_fp = Path(output_audio_fp)
+
+		cmd = [
+			"ffmpeg",
+			"-y",  # Overwrite output
+			"-i", str(inp_audio_fp),
+			"-vn",  # No video
+			str(output_audio_fp)
+		]
+
+		try:
+			subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.STDOUT)
+		except subprocess.CalledProcessError:
+			raise RuntimeError(f"FFmpeg failed to convert {inp_audio_fp} to {output_audio_fp}")
+			
+		return output_audio_fp

modusa/io/audio_loader.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+
+from modusa.io import ModusaIO
+from modusa.signals import AudioSignal
+from modusa.decorators import validate_args_type
+from pathlib import Path
+import tempfile
+import numpy as np
+
+class AudioLoader(ModusaIO):
+	"""
+	Loads audio from various sources like filepath, YouTube, etc.
+	
+	Note
+	----
+	- All `from_` methods return :class:`~modusa.signals.AudioSignal` instance.
+	
+	"""
+	
+	#--------Meta Information----------
+	_name = "Audio Loader"
+	_description = "Loads audio from various sources."
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-05"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+
+	@staticmethod
+	@validate_args_type()
+	def from_youtube(url: str, sr: int | None = None) -> "AudioSignal":
+		"""
+		Loads audio from youtube url using :class:`~modusa.io.YoutubeDownloader`,
+		:class:`~modusa.io.AudioConverter` and `librosa`.
+
+		.. code-block:: python
+			
+			from modusa.io import AudioSignalLoader
+		
+			# From youtube
+			audio_signal = AudioSignalLoader.from_youtube(
+				url="https://www.youtube.com/watch?v=lIpw9-Y_N0g", 
+				sr=None
+			)
+
+		PARAMETERS
+		----------
+		url: str
+			Link to the YouTube video.
+		sr: int
+			Sampling rate to load the audio in.
+		
+		Returns
+		-------
+		
+		AudioSignal:
+			`Audio signal` instance with loaded audio content from YouTube.
+		"""
+
+		from modusa.io import YoutubeDownloader, AudioConverter
+		import librosa
+		
+		# Download the audio in temp directory using tempfile module
+		with tempfile.TemporaryDirectory() as tmpdir:
+			audio_fp: Path = YoutubeDownloader.download(url=url, content_type="audio", output_dir=Path(tmpdir))
+			
+			# Convert the audio to ".wav" form for loading
+			wav_audio_fp: Path = AudioConverter.convert(inp_audio_fp=audio_fp, output_audio_fp=audio_fp.with_suffix(".wav"))
+			
+			# Load the audio in memory and return that
+			audio_data, audio_sr = librosa.load(wav_audio_fp, sr=sr)
+		
+		audio = AudioSignal(y=audio_data, sr=sr, title=audio_fp.stem)
+
+		return audio
+	
+	@staticmethod
+	@validate_args_type()
+	def from_fp(fp: str | Path, sr: int | None = None) -> AudioSignal:
+		"""
+		Loads audio from a filepath using `librosa`.
+
+		.. code-block:: python
+			
+			from modusa.io import AudioSignalLoader
+			
+			# From file
+			audio_signal = AudioSignalLoader.from_fp(
+				fp="path/to/audio.wav", 
+				sr=None
+			)
+
+		Parameters
+		----------
+		fp: str | Path
+			Local filepath of the audio.
+		sr: int | None
+			Sampling rate to load the audio in.
+		
+		Returns
+		-------
+		AudioSignal
+			`Audio signal` instance with loaded audio content from filepath.
+		
+		"""
+		import librosa
+		
+		fp = Path(fp)
+		y, sr = librosa.load(fp, sr=sr)
+		
+		audio_signal = AudioSignal(y=y, sr=sr, title=fp.name)
+		
+		return audio_signal
+	
+	
+	@staticmethod
+	def from_array(y: np.ndarray, t: np.ndarray | None = None) -> AudioSignal:
+		"""
+		Loads audio from numpy arrays.
+
+		.. code-block:: python
+			
+			from modusa.io import AudioSignalLoader
+			import numpy as np
+			
+			# From numpy array
+			audio_signal = AudioSignalLoader.from_array(
+				x=np.random.random((100, )),
+				t = None # Automatically creates time index (integer)
+			)
+
+		Parameters
+		----------
+		y: np.ndarray
+			Data of the audio signal.
+		t: np.ndarray | None
+			Corresponding time stamps of the audio signal.
+		
+		Returns
+		-------
+		AudioSignal
+			`Audio signal` instance with loaded audio content from arrays.
+		"""
+		
+		return  AudioSignal(y=y, t=t)
+	
+	@staticmethod
+	def from_array_with_sr(y: np.ndarray, sr: int) -> AudioSignal:
+		"""
+		Loads audio with a given sampling rate.
+	
+		.. code-block:: python
+			
+			from modusa.io import AudioSignalLoader
+			import numpy as np
+			
+			# From numpy array
+			audio_signal = AudioSignalLoader.from_array_with_sr(
+				x=np.random.random((100, )),
+				sr = 100 # Automatically generates time index
+			)
+
+		Parameters
+		----------
+		y: np.ndarray
+			Data of the audio signal.
+		sr: int
+			Sampling rate of the audio signal.
+		
+		Returns
+		-------
+		AudioSignal
+			`Audio signal` instance with loaded audio content from sampling rate.
+		"""
+		
+		return AudioSignal(y=y, sr=sr)
+	
+	@staticmethod
+	def from_list(y: list, t: list) -> AudioSignal:
+		"""
+		Loads `AudioSignal` instance from python list.
+		
+		.. code-block:: python
+			
+			from modusa.io import AudioSignalLoader
+			
+			# From list
+			audio_signal = AudioSignalLoader.from_list(
+				y=[1, 2, 3, 2, 3],
+				t = [0.1, 0.2, 0.3, 0.4, 0.5]
+			)
+
+		Parameters
+		----------
+		y: list
+			Data of the audio signal.
+		t: np.ndarray | None
+			Corresponding time stamps of the audio signal.
+		
+		Returns
+		-------
+		AudioSignal
+			`Audio signal` instance with loaded audio content from python list.
+		"""
+		y = np.array(y)
+		t = np.array(t)
+		
+		return AudioSignal(y=y, t=t)
+		
+		

modusa/io/audio_player.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.io import ModusaIO
+from IPython.display import display, HTML, Audio
+import numpy as np
+
+class AudioPlayer(ModusaIO):
+	"""
+	
+	"""
+	
+	#--------Meta Information----------
+	_name = "Audio Player"
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-08"
+	#----------------------------------
+	
+	@staticmethod
+	def play(
+		y: np.ndarray,
+		sr: int,
+		regions: list[tuple[float, float]] | None = None,
+		title: str | None = None
+	) -> None:
+		"""
+		Plays audio clips for given regions in Jupyter Notebooks.
+
+		Parameters
+		----------
+		y : np.ndarray
+			Audio time series.
+		sr : int
+			Sampling rate.
+		regions : list of (float, float), optional
+			Regions to extract and play (in seconds).
+		title : str, optional
+			Title to display above audio players.
+
+		Returns
+		-------
+		None
+		"""
+		if not AudioPlayer._in_notebook():
+			return
+		
+		if title:
+			display(HTML(f"<h4>{title}</h4>"))
+			
+		if regions:
+			for i, (start_sec, end_sec) in enumerate(regions):
+				start_sample = int(start_sec * sr)
+				end_sample = int(end_sec * sr)
+				clip = y[start_sample:end_sample]
+				
+				display(HTML(f"<b>Clip {i+1}</b>: {start_sec:.2f}s → {end_sec:.2f}s"))
+				display(Audio(data=clip, rate=sr))
+		else:
+			display(Audio(data=y, rate=sr))
+			
+	@staticmethod
+	def _in_notebook() -> bool:
+		try:
+			from IPython import get_ipython
+			shell = get_ipython()
+			return shell and shell.__class__.__name__ == "ZMQInteractiveShell"
+		except ImportError:
+			return False

modusa/io/base.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+
+from abc import ABC, abstractmethod
+
+class ModusaIO(ABC):
+	"""
+	Base class for all I/O components: loaders, savers, recorders, etc.
+	
+	>>> modusa-dev create io
+
+	.. code-block:: python
+		
+		# General template of a subclass of ModusaIO
+		from modusa.io import ModusaIO
+
+		class MyCustomIOClass(ModusaIO):
+			#--------Meta Information----------
+			_name = "My Custom I/O"
+			_description = "My custom class for I/O."
+			_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 IO related tools built for the modusa framework.
+	- In order to create an IO tool, you can use modusa-dev CLI to generate an IO template.
+	- It is recommended to treat subclasses of ModusaIO as namespaces and define @staticmethods with control parameters, rather than using instance-level __init__ methods.
+	"""
+	
+	#--------Meta Information----------
+	_name: str = "Modusa I/O"
+	_description: str = "Base class for any I/O in the Modusa framework."
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-06"
+	#----------------------------------