torch-l1-snr 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

{torch_l1_snr-0.0.2.dist-info → torch_l1_snr-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: torch-l1-snr
-Version: 0.0.2
+Version: 0.0.4
 Summary: L1-SNR loss functions for audio source separation in PyTorch
 Home-page: https://github.com/crlandsc/torch-l1-snr
 Author: Christopher Landscaping
@@ -32,28 +32,29 @@ Dynamic: license-file
 
 [![LICENSE](https://img.shields.io/github/license/crlandsc/torch-l1snr)](https://github.com/crlandsc/torch-l1snr/blob/main/LICENSE) [![GitHub Repo stars](https://img.shields.io/github/stars/crlandsc/torch-l1snr)](https://github.com/crlandsc/torch-l1snr/stargazers)
 
-# torch-l1-snr
-
 A PyTorch implementation of L1-based Signal-to-Noise Ratio (SNR) loss functions for audio source separation. This package provides implementations and novel extensions based on concepts from recent academic papers, offering flexible and robust loss functions that can be easily integrated into any PyTorch-based audio separation pipeline.
 
-The core `L1SNRLoss` is based on the loss function described in [1], while `L1SNRDBLoss` and `STFTL1SNRDBLoss` are extensions of the adaptive level-matching regularization technique proposed in [2].
+The core `L1SNRLoss` is based on the loss function described in [[1]](https://arxiv.org/abs/2309.02539), while `L1SNRDBLoss` and `STFTL1SNRDBLoss` are extensions of the adaptive level-matching regularization technique proposed in [[2]](https://arxiv.org/abs/2501.16171).
 
 ## Features
 
-- **Time-Domain L1SNR Loss**: A basic, time-domain L1-SNR loss, based on [1].
-- **Regularized Time-Domain L1SNRDBLoss**: An extension of the L1SNR loss with adaptive level-matching regularization from [2], plus an optional L1 loss component.
-- **Multi-Resolution STFT L1SNRDBLoss**: A spectrogram-domain version of the loss from [2], calculated over multiple STFT resolutions.
+- **Time-Domain L1SNR Loss**: A basic, time-domain L1-SNR loss, based on [[1]](https://arxiv.org/abs/2309.02539).
+- **Regularized Time-Domain L1SNRDBLoss**: An extension of the L1SNR loss with adaptive level-matching regularization from [[2]](https://arxiv.org/abs/2501.16171), plus an optional L1 loss component.
+- **Multi-Resolution STFT L1SNRDBLoss**: A spectrogram-domain version of the loss from [[2]](https://arxiv.org/abs/2501.16171), calculated over multiple STFT resolutions.
 - **Modular Stem-based Loss**: A wrapper that combines time and spectrogram domain losses and can be configured to run on specific stems.
 - **Efficient & Robust**: Includes optimizations for pure L1 loss calculation and robust handling of `NaN`/`inf` values and short audio segments.
 
 ## Installation
 
-<!-- Add PyPI badges once the package is published -->
-<!-- [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/torch-l1snr)](https://pypi.org/project/torch-l1snr/) -->
-<!-- [![PyPI - Version](https://img.shields.io/pypi/v/torch-l1snr)](https://pypi.org/project/torch-l1snr/) -->
-<!-- [![Number of downloads from PyPI per month](https://img.shields.io/pypi/dm/torch-l1snr)](https://pypi.org/project/torch-l1snr/) -->
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/torch-l1-snr)](https://pypi.org/project/torch-l1-snr/) [![PyPI - Version](https://img.shields.io/pypi/v/torch-l1-snr)](https://pypi.org/project/torch-l1-snr/) [![Number of downloads from PyPI per month](https://img.shields.io/pypi/dm/torch-l1-snr)](https://pypi.org/project/torch-l1-snr/)
+
+## Install from PyPI
+
+```bash
+pip install torch-l1-snr
+```
 
-You can install the package directly from GitHub:
+## Install from GitHub
 
 ```bash
 pip install git+https://github.com/crlandsc/torch-l1snr.git
@@ -90,9 +91,13 @@ from torch_l1snr import L1SNRDBLoss
 estimates = torch.randn(4, 32000)  # Batch of 4, 32000 samples
 actuals = torch.randn(4, 32000)
 
-# Initialize the loss function
-# l1_weight=0.1 blends L1SNR with 10% L1 loss
-loss_fn = L1SNRDBLoss(l1_weight=0.1)
+# Initialize the loss function with regularization enabled
+# l1_weight=0.1 blends L1SNR+Regularization with 10% L1 loss
+loss_fn = L1SNRDBLoss(
+    name="l1_snr_db_loss",
+    use_regularization=True,  # Enable adaptive level-matching regularization
+    l1_weight=0.1             # 10% L1 loss, 90% L1SNR + regularization
+)
 
 # Calculate loss
 loss = loss_fn(estimates, actuals)
@@ -112,8 +117,11 @@ estimates = torch.randn(4, 32000)
 actuals = torch.randn(4, 32000)
 
 # Initialize the loss function
-# Uses multiple STFT resolutions by default
-loss_fn = STFTL1SNRDBLoss(l1_weight=0.0) # Pure L1SNR + Regularization
+# Uses multiple STFT resolutions by default: [512, 1024, 2048] FFT sizes
+loss_fn = STFTL1SNRDBLoss(
+    name="stft_l1_snr_db_loss",
+    l1_weight=0.0              # Pure L1SNR (no regularization, no L1)
+)
 
 # Calculate loss
 loss = loss_fn(estimates, actuals)
@@ -137,9 +145,12 @@ actuals = torch.randn(2, 2, 44100)
 
 # --- Configuration ---
 loss_fn = MultiL1SNRDBLoss(
-    weight=1.0,               # Overall weight for this loss
-    spec_weight=0.7,          # 70% spectrogram loss, 30% time-domain loss
-    l1_weight=0.1,           # Use 10% L1, 90% L1SNR+Reg
+    name="multi_l1_snr_db_loss",
+    weight=1.0,                    # Overall weight for this loss
+    spec_weight=0.6,               # 60% spectrogram loss, 40% time-domain loss
+    l1_weight=0.1,                 # Use 10% L1, 90% L1SNR+Reg in both domains
+    use_time_regularization=True,  # Enable regularization in time domain
+    use_spec_regularization=False  # Disable regularization in spec domain
 )
 loss = loss_fn(estimates, actuals)
 print(f"Multi-domain Loss: {loss.item()}")
@@ -155,7 +166,7 @@ The goal of these loss functions is to provide a perceptually-informed and robus
 
 #### Level-Matching Regularization
 
-A key feature of `L1SNRDBLoss` is the adaptive regularization term, as described in [2]. This component calculates the difference in decibel-scaled root-mean-square (dBRMS) levels between the estimated and actual signals. An adaptive weight (`lambda`) is applied to this difference, which increases when the model incorrectly silences a non-silent target. This encourages the model to learn the correct output level and specifically avoids the model collapsing to a trivial silent solution when uncertain.
+A key feature of `L1SNRDBLoss` is the adaptive regularization term, as described in [[2]](https://arxiv.org/abs/2501.16171). This component calculates the difference in decibel-scaled root-mean-square (dBRMS) levels between the estimated and actual signals. An adaptive weight (`lambda`) is applied to this difference, which increases when the model incorrectly silences a non-silent target. This encourages the model to learn the correct output level and specifically avoids the model collapsing to a trivial silent solution when uncertain.
 
 #### Multi-Resolution Spectrogram Analysis
 
@@ -194,8 +205,8 @@ The loss functions implemented here are based on the work of the authors of the
 
 ## References
 
-[1] K. N. Watcharasupat, C.-W. Wu, Y. Ding, I. Orife, A. J. Hipple, P. A. Williams, S. Kramer, A. Lerch, and W. Wolcott, "A Generalized Bandsplit Neural Network for Cinematic Audio Source Separation," IEEE Open Journal of Signal Processing, 2023. (arXiv:2309.02539)
+[1] K. N. Watcharasupat, C.-W. Wu, Y. Ding, I. Orife, A. J. Hipple, P. A. Williams, S. Kramer, A. Lerch, and W. Wolcott, "A Generalized Bandsplit Neural Network for Cinematic Audio Source Separation," IEEE Open Journal of Signal Processing, 2023. [arXiv:2309.02539](https://arxiv.org/abs/2309.02539)
 
-[2] K. N. Watcharasupat and A. Lerch, "Separate This, and All of these Things Around It: Music Source Separation via Hyperellipsoidal Queries," arXiv:2501.16171.
+[2] K. N. Watcharasupat and A. Lerch, "Separate This, and All of these Things Around It: Music Source Separation via Hyperellipsoidal Queries," [arXiv:2501.16171](https://arxiv.org/abs/2501.16171).
 
-[3] K. N. Watcharasupat and A. Lerch, "A Stem-Agnostic Single-Decoder System for Music Source Separation Beyond Four Stems," Proceedings of the 25th International Society for Music Information Retrieval Conference, 2024. (arXiv:2406.18747) 
+[3] K. N. Watcharasupat and A. Lerch, "A Stem-Agnostic Single-Decoder System for Music Source Separation Beyond Four Stems," Proceedings of the 25th International Society for Music Information Retrieval Conference, 2024. [arXiv:2406.18747](https://arxiv.org/abs/2406.18747) 

torch_l1_snr-0.0.4.dist-info/RECORD

@@ -0,0 +1,7 @@
+torch_l1_snr-0.0.4.dist-info/licenses/LICENSE,sha256=JdS2Pv6DDs3jvXHACGdcHYdiFMe9EO1XGeHkEHLTr8Y,1079
+torch_l1snr/__init__.py,sha256=pR9jg3fjTKt_suZoVDC67tqB7EWRkbfaXaPP7pYQrlQ,220
+torch_l1snr/l1snr.py,sha256=aqmtNfT_8A0IRI9jiVGwNse3igBvelQGKnjfe23Xh7w,35304
+torch_l1_snr-0.0.4.dist-info/METADATA,sha256=pB7DvZ6BdvCshcDqOTkJNqekh97qXNaPc7tnNzBqJVk,11143
+torch_l1_snr-0.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+torch_l1_snr-0.0.4.dist-info/top_level.txt,sha256=NfaRND6pcjZ7-035d4XAg8xJuz31EEU210Y9xWeFOxc,12
+torch_l1_snr-0.0.4.dist-info/RECORD,,

torch_l1_snr-0.0.2.dist-info/RECORD

@@ -1,7 +0,0 @@
-torch_l1_snr-0.0.2.dist-info/licenses/LICENSE,sha256=JdS2Pv6DDs3jvXHACGdcHYdiFMe9EO1XGeHkEHLTr8Y,1079
-torch_l1snr/__init__.py,sha256=pR9jg3fjTKt_suZoVDC67tqB7EWRkbfaXaPP7pYQrlQ,220
-torch_l1snr/l1snr.py,sha256=aqmtNfT_8A0IRI9jiVGwNse3igBvelQGKnjfe23Xh7w,35304
-torch_l1_snr-0.0.2.dist-info/METADATA,sha256=C8sH_v1T2LYRCwCiLMMJkrnh4l-chYzjZYbD2xyI8gg,10370
-torch_l1_snr-0.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-torch_l1_snr-0.0.2.dist-info/top_level.txt,sha256=NfaRND6pcjZ7-035d4XAg8xJuz31EEU210Y9xWeFOxc,12
-torch_l1_snr-0.0.2.dist-info/RECORD,,