inaVAMOS 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,55 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ jobs:
8
+ tests:
9
+ uses: ./.github/workflows/tests.yml
10
+
11
+ build:
12
+ needs: tests
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - uses: actions/checkout@v5
16
+
17
+ - uses: actions/setup-python@v6
18
+ with:
19
+ python-version: "3.13"
20
+
21
+ - name: Check that the release tag matches the package version
22
+ run: |
23
+ version=$(python -c "import re; print(re.search(r'__version__ = \"(.+)\"', open('src/inavamos/__init__.py').read())[1])")
24
+ tag="${GITHUB_REF_NAME#v}"
25
+ if [ "$tag" != "$version" ]; then
26
+ echo "::error::Release tag $GITHUB_REF_NAME does not match __version__ = $version in src/inavamos/__init__.py"
27
+ exit 1
28
+ fi
29
+
30
+ - name: Build
31
+ run: |
32
+ pip install build twine
33
+ python -m build
34
+ twine check --strict dist/*
35
+
36
+ - uses: actions/upload-artifact@v4
37
+ with:
38
+ name: dist
39
+ path: dist/
40
+
41
+ publish:
42
+ needs: build
43
+ runs-on: ubuntu-latest
44
+ environment:
45
+ name: pypi
46
+ url: https://pypi.org/p/inaVAMOS
47
+ permissions:
48
+ id-token: write # trusted publishing: no PyPI token stored in the repository
49
+ steps:
50
+ - uses: actions/download-artifact@v5
51
+ with:
52
+ name: dist
53
+ path: dist/
54
+
55
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,41 @@
1
+ name: Tests
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ workflow_call: # reused by the publish workflow
8
+
9
+ jobs:
10
+ tests:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ fail-fast: false
14
+ matrix:
15
+ python-version: ["3.10", "3.13"]
16
+ steps:
17
+ - uses: actions/checkout@v5
18
+
19
+ - uses: actions/setup-python@v6
20
+ with:
21
+ python-version: ${{ matrix.python-version }}
22
+
23
+ - name: Install ffmpeg
24
+ run: sudo apt-get update && sudo apt-get install -y ffmpeg
25
+
26
+ - name: Install package
27
+ # CPU build of torch: much smaller than the default CUDA build
28
+ run: |
29
+ pip install torch --index-url https://download.pytorch.org/whl/cpu
30
+ pip install -e ".[test]"
31
+
32
+ - name: Cache models and test media
33
+ uses: actions/cache@v4
34
+ with:
35
+ path: |
36
+ ~/.cache/huggingface/hub
37
+ .pytest_cache
38
+ key: models-${{ hashFiles('src/inavamos/models.py') }}
39
+
40
+ - name: Run tests
41
+ run: pytest -v
@@ -0,0 +1,10 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
7
+
8
+ # Maintenance script, not part of the package
9
+ convert_pt2_to_safetensors.py
10
+ converted/
@@ -0,0 +1,155 @@
1
+
2
+ # Pantagruel Research-only License
3
+ Dated 2026-02-19
4
+
5
+ ---
6
+
7
+ This License, limited to research & development activities, was created by the
8
+ members of the Pantagruel Consortium, a collaborative ANR research project
9
+ aimed at developing multimodal linguistic artificial intelligence (AI) models
10
+ for French, based on machine learning.
11
+
12
+ As part of this project, in order to make the AI models developed during the
13
+ Pantagruel project available to the research community, while respecting the
14
+ intellectual property rights of the data used for their training, this License
15
+ has been established for non-commercial use and research purposes.
16
+
17
+ This License governs the use of the AI models (and its derivates).
18
+
19
+ **THEREFORE, You agree to the following:**
20
+
21
+ ## ARTICLE 1 – Definition
22
+ - **“License”** means the terms and conditions for accessing, using,
23
+ reproducing and distributing the Models and their Derivatives, as defined in
24
+ this document.
25
+ - **“Model”** means the Artificial Intelligence (AI) Model, as well as its
26
+ components, including algorithms, learned weights, parameters (including
27
+ optimiser states), inference code and any other associated elements made
28
+ available by the Licensor under this License.
29
+ - **“Derivatives”** means any modifications made to the Model, works based
30
+ on the Model, or any other model created from the weights, parameters,
31
+ activations or outputs of the Model towards another model, including – but
32
+ not limited to – distillation methods involving the use of intermediate
33
+ representations or methods based on the generation of synthetic data by the
34
+ Model to train the other model.
35
+ - **“Output”** means the outputs produced by the operation of the Model or
36
+ its Derivatives in response to an input. The Output does not include any
37
+ element of the Model or a Derivative of the Model.
38
+ - **“Licensor”** means any person holding intellectual property rights to
39
+ the Model, in particular the members of the Pantagruel Consortium (as described
40
+ on the website available at: https://pantagruel.imag.fr/) or any entities
41
+ authorised by them to grant the License.
42
+ - **"R&D Activities"** means use of the Model, its Derivatives and Outputs in
43
+ non-commercial, exploratory or experimental activities to advance knowledge,
44
+ test concepts, or improve technologies. R&D Purposes excludes activities
45
+ planned or anticipated for use outside of scientific research and development.
46
+ This expressly excludes direct commercial operations and revenue-generating
47
+ activities. R&D Activities may include, without limitation, any context, use
48
+ case or application for research, development, testing, internal evaluation
49
+ (except for any internal use by employees as part of the company's commercial
50
+ activities), and demonstrations.
51
+ - **“You” (or “Your”)** refers to any natural or legal person
52
+ exercising the rights granted by this License and/or using the Model. It is
53
+ specified that only the following entities may use the Model: research
54
+ organisations, publicly accessible libraries, museums, archive services or
55
+ cinematographic, audiovisual or sound heritage institutions, and all natural
56
+ persons affiliated with them for the purpose of carrying out R&D Activities.
57
+
58
+ ## ARTICLE 2 – Conditions of use for the Model and its Derivatives
59
+ Subject to compliance with the terms and conditions of this License, the
60
+ Licensor hereby grants you a worldwide, non-exclusive, royalty-free, fee-free
61
+ license, for the duration of the intellectual property rights, to reproduce,
62
+ prepare, publicly display, perform, sublicense, and distribute the Model and
63
+ its Derivatives, solely for R&D Activities.
64
+
65
+ You may distribute the Model or any Derivative created by You or for You under
66
+ additional or different terms, provided that:
67
+ - You are a natural person for the R&D Activities and are affiliated with a
68
+ research organization, a publicly accessible library, a museum, an archive
69
+ service, or a cinematographic, audiovisual or sound heritage institution;
70
+ - In any case, the use and modification of the Model and/or Derivatives created
71
+ by or for You remain governed by the terms and conditions of the License;
72
+ - You include the terms of the License and the usage restrictions attached to
73
+ the Model and its Derivatives;
74
+ - You include, in any Derivative created by You or for You, visible notices
75
+ indicating the elements you have modified on the relevant Model; and
76
+ - All terms you impose on third party recipients regarding Derivatives of the
77
+ Model created by You or for You do not conflict with any of the terms and
78
+ conditions of the License.
79
+
80
+ No trademark license is granted under the License and, in relation to the
81
+ Model, You may not use any name or trademark held by or associated with any of
82
+ the Licensors or any of their affiliates, except (i) to the extent necessary
83
+ for reasonable and customary use to describe and distribute the Model and any
84
+ Derivatives created, and (ii) for attribution purposes as required by the
85
+ License.
86
+
87
+ ## ARTICLE 3 – Usage Restrictions
88
+ You are not authorized to:
89
+ - Provide or use the Model or Its Derivates in the course of a commercial
90
+ activity, whether in return for payment or free of charge, in any medium or
91
+ form, including but not limited to through a hosted or managed service (e.g.
92
+ SaaS, cloud instances, etc.), or behind a software layer (artificial
93
+ intelligence system).
94
+ - Provide or use the Model or its Derivates for any purpose contrary to laws
95
+ and regulations.
96
+
97
+ If You want to use a Model or a Derivative for any purpose that is not
98
+ expressly authorized under this License, please contact the Pantagruel
99
+ Consortium at the following e-mail address:
100
+ pantagruel-licence@univ-grenoble-alpes.fr .
101
+
102
+ ## ARTICLE 4 – Outputs intellectual Propriety
103
+ Licensors claim no intellectual property rights on the Outputs. You are solely
104
+ responsible for the Outputs You generate and their subsequent uses.
105
+
106
+ ## ARTICLE 5 – Warranties and liabilities limitations
107
+ The Model is provided “as is”, without any express or implied warranty of
108
+ any kind, including warranties of fitness for a particular purpose.
109
+
110
+ The Licensor makes no representation or warranty that the Model and its
111
+ Derivatives will be error-free, secure, or will enable You or any third party
112
+ to achieve any particular result or generate any specific content. You are
113
+ solely responsible for determining the suitability of using or distributing the
114
+ Model and Derivatives, and You assume all risks associated with implementing
115
+ the License.
116
+
117
+ The Licensor is not obliged to maintain, update, or provide support for any
118
+ Model or Derivative.
119
+
120
+ In no event, except where required by applicable law (such as in cases of
121
+ wilful misconduct or gross negligence), shall the Licensor be held liable to
122
+ You for any damages, including any direct, indirect, special, incidental, or
123
+ consequential damages of any kind resulting from the License or from the use or
124
+ inability to use the Model and its Derivatives (including, without limitation,
125
+ damages for loss of data, loss of goodwill, loss of profits or anticipated
126
+ savings, business interruption, computer failure or malfunction, or any damage
127
+ caused by malicious software or security breaches). These limitations of
128
+ liability are an essential element of the License.
129
+
130
+ You agree to hold the Licensor harmless against any claim, damage, or loss
131
+ arising from or related to Your use or distribution of the Model and
132
+ Derivatives.
133
+
134
+ ## ARTICLE 6 – Duration
135
+ The License takes effect on the date You accept it or access the relevant Model
136
+ or its Derivatives and shall remain in force for the duration of the
137
+ intellectual property rights.
138
+
139
+ ## ARTICLE 7 – Other provisions
140
+ This License will be governed by the laws of France.
141
+
142
+ The courts of Paris shall have exclusive jurisdiction of any dispute arising
143
+ out of this License.
144
+
145
+ If any provision of this License is held to be invalid, illegal or
146
+ unenforceable, the remaining provisions shall be unaffected thereby and remain
147
+ valid as if such provision had not been set forth herein.
148
+
149
+
150
+ _This document is provided solely for convenience as an unofficial translation
151
+ of the original French version of the License. In the event of any
152
+ inconsistency, discrepancy, or ambiguity between this translation and the
153
+ French version, the French version shall prevail and be legally binding for all
154
+ purposes._
155
+
@@ -0,0 +1,175 @@
1
+
2
+ # Pantagruel Licence Recherche
3
+ En date du 2026-02-19
4
+
5
+ _An unofficial English translation of this License can be found in the file
6
+ [LICENSE.en.md](LICENSE.en.md).
7
+ In the event of any inconsistency, discrepancy, or ambiguity between this
8
+ translation and the French version, the French version shall prevail and be
9
+ legally binding for all purposes._
10
+
11
+ ---
12
+
13
+ Cette Licence, limitée aux activités de recherche et développement, a été
14
+ créée par les membres du Consortium Pantagruel, un projet collaboratif de
15
+ recherche ANR, visant au développement de modèles d’intelligence
16
+ artificielle (IA) linguistiques multimodaux pour le français, basés sur
17
+ l’apprentissage automatique.
18
+
19
+ Dans le cadre de ce projet, afin d’ouvrir les modèles d’IA développés
20
+ durant le projet Pantagruel à la communauté des chercheurs, tout en
21
+ respectant les droits de propriété intellectuelle des données utilisées
22
+ pour leur entraînement, la présente Licence a été établie, pour une
23
+ utilisation non commerciale et à des fins de recherche.
24
+
25
+ Cette licence régit l’utilisation des Modèles d’IA (et de leurs
26
+ Dérivés) y étant soumis. En accédant, utilisant, modifiant ou distribuant
27
+ un Modèle mis à disposition, ou en créant, utilisant ou distribuant un
28
+ Dérivé du Modèle, Vous acceptez d’être lié par la présente licence.
29
+
30
+ **EN CONSÉQUENCE, Vous acceptez ce qui suit :**
31
+
32
+ ## ARTICLE 1 – Definition
33
+ - **« Licence »** désigne les termes et conditions d’accès,
34
+ d’utilisation, de reproduction et de distribution des Modèles et de leurs
35
+ Dérivés, tels que définis dans le présent document.
36
+ - **« Modèle »** : désigne le Modèle d’Intelligence artificielle (IA),
37
+ ainsi que leurs éléments, comprenant les algorithmes, poids appris,
38
+ paramètres (y compris les états de l’optimiseur), code d’inférence et
39
+ tout autre élément associé mis à disposition par le Concédant en vertu de
40
+ la présente Licence.
41
+ - **« Dérivés »** désigne toutes modifications apportées au Modèle,
42
+ travaux basés sur le Modèle, ou tout autre modèle créé à partir des
43
+ poids, paramètres, activations ou sorties du Modèle vers un autre modèle, y
44
+ compris – mais sans s’y limiter – les méthodes de distillation
45
+ impliquant l’utilisation de représentations intermédiaires ou les méthodes
46
+ basées sur la génération de données synthétiques par le Modèle pour
47
+ entraîner l’autre modèle.
48
+ - **« Résultat »** désigne les résultats produits par le fonctionnement du
49
+ Modèle ou de ses Dérivés en réponse à une entrée. Le Résultat n’inclut
50
+ aucun élément du Modèle ou d’un Dérivé du Modèle.
51
+ - **« Concédant »** désigne toute personne titulaire des droits de
52
+ propriété intellectuelle sur le Modèle, en particulier les membres du
53
+ Consortium Pantagruel (tel que décris sur le site disponible à l’adresse :
54
+ https://pantagruel.imag.fr/) ou les entités autorisées par ces derniers à
55
+ accorder la Licence.
56
+ - **« Activités de R&D »** désigne l’utilisation du Modèle, de ses
57
+ Dérivés et des Résultats dans des activités non commerciales, exploratoires
58
+ ou expérimentales visant à faire progresser les connaissances, tester des
59
+ concepts ou améliorer des technologies. Les finalités de R&D excluent les
60
+ activités planifiées ou envisagées pour un usage hors du cadre de la
61
+ recherche et du développement scientifique. Cela exclut expressément les
62
+ opérations commerciales en direct et les activités génératrices de revenus.
63
+ Les Activités de R&D peuvent inclure, sans s’y limiter, tout contexte, cas
64
+ d’utilisation ou application pour la recherche, le développement, les tests,
65
+ l’évaluation interne (à l’exception de toute utilisation interne par les
66
+ employés dans le cadre des activités commerciales de l’entreprise) et des
67
+ démonstrations.
68
+ - **« Vous » (ou « Votre »)** désigne une personne physique ou morale
69
+ exerçant les droits accordés par la présente Licence et/ou utilisant le
70
+ Modèle. Il est précisé que seules les personnes suivantes peuvent utiliser
71
+ le Modèle : les organismes de recherche, les bibliothèques accessibles au
72
+ public, les musées, les services d'archives ou les institutions dépositaires
73
+ du patrimoine cinématographique, audiovisuel ou sonore, et toutes les
74
+ personnes physiques qui, pour l'exercice d'Activités de R&D, leur sont
75
+ rattachées.
76
+
77
+ ## ARTICLE 2 – Droits d’utilisation du Modèle et ses Dérivés
78
+ Sous réserve du respect des termes et conditions de la présente Licence, le
79
+ Concédant vous accorde par la présente, une Licence mondiale, non exclusive,
80
+ sans frais, libre de redevance, pour la durée des droits de propriété
81
+ intellectuelle pour reproduire, préparer, afficher publiquement, exécuter,
82
+ accorder des sous-licences et distribuer le Modèle, ainsi ses Dérivés,
83
+ uniquement pour des Activités de R&D.
84
+
85
+ Vous pouvez distribuer le Modèle ou tout Dérivé créé par Vous ou pour Vous
86
+ selon des conditions supplémentaires ou différentes, à condition que :
87
+ - Vous soyez un chercheur pour l’exercice d’Activités de R&D et/ou que
88
+ vous soyez rattachés à un organisme de recherche, une bibliothèque
89
+ accessible au public, un musée, un service d'archives ou une institution
90
+ dépositaire du patrimoine cinématographique, audiovisuel ou sonore,
91
+ - En tout état de cause, l’utilisation et la modification du Modèle et/ou
92
+ des Dérivés créés par ou pour Vous demeurent régies par les termes et
93
+ conditions de la License ;
94
+ - Vous incluiez les conditions de la License et les restrictions
95
+ d’utilisation attachées au Modèle et ses Dérivés ;
96
+ - Vous incluiez, dans tout Dérivé créé par Vous ou pour Vous, des mentions
97
+ visibles indiquant les éléments que vous avez modifié sur le Modèle
98
+ concerné ; et
99
+ - Toutes les conditions que vous imposez à des tiers destinataires concernant
100
+ les Dérivés du Modèle créés par Vous ou pour Vous ne soient pas en
101
+ contradiction avec l’un quelconque des termes et conditions de la Licence.
102
+
103
+ Aucune licence de marque n’est accordée dans le cadre de la Licence et, en
104
+ lien avec le Modèle, Vous ne pouvez utiliser aucun nom ou marque détenu par
105
+ ou associé à l’un des Concédant ou à l’un de ses affiliés, sauf (i)
106
+ dans la mesure nécessaire à une utilisation raisonnable et habituelle pour
107
+ décrire et distribuer le Modèle et les Dérivés créés, et (ii) pour des
108
+ besoins d’attribution tels qu’exigés par la Licence.
109
+
110
+ ## ARTICLE 3 – Restrictions d’usage
111
+ Vous n’êtes pas autorisé à :
112
+ - fournir ou utiliser le Modèle ou ses Dérivés dans le cadre d’une
113
+ activité commerciale, que ce soit en contrepartie d’un paiement ou
114
+ gratuitement, sous quelque forme ou support que ce soit, y compris mais sans
115
+ s’y limiter via un service hébergé ou géré (ex. SaaS, instances cloud,
116
+ etc.), ou via un outil logiciel (système d’intelligence artificiel) ;
117
+ - fournir ou utiliser le Modèle et les Dérivés pour des utilisations
118
+ contraires aux lois et réglementations.
119
+
120
+ Si Vous souhaitez utiliser un Modèle ou un Dérivé à toute fin qui n’est
121
+ pas expressément autorisée par la présente Licence, veuillez contacter le
122
+ Consortium Pantagruel à l’adresse e-mail suivante :
123
+ pantagruel-licence@univ-grenoble-alpes.fr
124
+
125
+ ## ARTICLE 4 – Propriété des Résultats
126
+ Le Concédant ne revendique aucun droit de propriété sur les Résultats. Vous
127
+ êtes seul responsable des Résultats que Vous générez ainsi que de leurs
128
+ utilisations ultérieures.
129
+
130
+ ## ARTICLE 5 – Garanties et limitations de responsabilités
131
+ Le Modèle est fourni « en l’état », sans aucune garantie expresse ou
132
+ implicite de quelque nature que ce soit, y compris les garanties
133
+ d’adéquation à un usage particulier.
134
+
135
+ Le Concédant ne déclare ni ne garantit que le Modèle et les Dérivés seront
136
+ exempts d’erreurs, seront sûrs ou permettront à Vous ou à tout tiers
137
+ d’atteindre un quelconque résultat ou de générer un quelconque contenu.
138
+ Vous êtes seul responsable de déterminer l’adéquation de l’utilisation
139
+ ou de la distribution du Modèle et Dérivés et assumez tous les risques
140
+ associés à la mise en œuvre de la License.
141
+
142
+ Le Concédant n’est pas tenu de maintenir, mettre à jour ou assurer le
143
+ support de tout Modèle ou Dérivé.
144
+
145
+ En aucun cas, sauf si la loi applicable l’exige (par exemple en cas d’actes
146
+ délibérés ou de faute lourde) le Concédant ne saurait être tenu
147
+ responsable envers Vous de tout dommage, y compris tout dommage direct,
148
+ indirect, spécial, accessoire ou consécutif de quelque nature que ce soit
149
+ résultant de la Licence ou de l’utilisation ou de l’impossibilité
150
+ d’utiliser le Modèle et ses Dérivés (y compris, sans limitation, les
151
+ dommages pour perte de données, perte de clientèle, perte de profits ou
152
+ d’économies escomptées, interruption de travail, panne ou dysfonctionnement
153
+ informatique, ou tout dommage causé par des programmes malveillants ou des
154
+ failles de sécurité). Ces limitations de responsabilité constituent un
155
+ élément déterminant de la Licence.
156
+
157
+ Vous acceptez de dégager de toute responsabilité le Concédant contre toute
158
+ réclamation, tout dommage ou toute perte résultant de ou liée à Votre
159
+ utilisation ou distribution du Modèle et Dérivés.
160
+
161
+ ## ARTICLE 6 – Durée
162
+ La Licence prend effet à la date de Votre acceptation de celle-ci ou de Votre
163
+ accès au Modèle concerné ou à ses Dérivés, et demeurera en vigueur pour
164
+ la durée des droits de propriété intellectuelle.
165
+
166
+ ## ARTICLE 7 – Divers
167
+ La Licence sera régie par le droit français.
168
+
169
+ Les tribunaux de Paris auront compétence exclusive pour tout litige découlant
170
+ des présentes.
171
+
172
+ Si une disposition de la Licence est jugée invalide, illégale ou
173
+ inapplicable, les autres dispositions n’en seront pas affectées et resteront
174
+ valides comme si ladite disposition n’avait pas été incluse aux présentes.
175
+
@@ -0,0 +1,216 @@
1
+ Metadata-Version: 2.5
2
+ Name: inaVAMOS
3
+ Version: 0.1.0
4
+ Summary: Voice And Music Open Segmenter: speech (voice activity) and music detection in audio and video files, based on SSL models from INA
5
+ Project-URL: Homepage, https://github.com/ina-foss/inaVAMOS
6
+ Project-URL: Issues, https://github.com/ina-foss/inaVAMOS/issues
7
+ Project-URL: VAD model, https://huggingface.co/ina-foss/ssl-vad-music2vec
8
+ Project-URL: Music detection model, https://huggingface.co/ina-foss/ssl-music-detection-music2vec
9
+ Author-email: Valentin Pelloin <vpelloin@ina.fr>
10
+ License-Expression: LicenseRef-Pantagruel-Research-License
11
+ License-File: LICENSE.en.md
12
+ License-File: LICENSE.md
13
+ Keywords: VAD,audio segmentation,music detection,self-supervised learning,speech,voice activity detection
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
17
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
18
+ Requires-Python: >=3.10
19
+ Requires-Dist: huggingface-hub>=0.23
20
+ Requires-Dist: librosa>=0.10
21
+ Requires-Dist: numpy
22
+ Requires-Dist: safetensors
23
+ Requires-Dist: torch>=2.2
24
+ Requires-Dist: transformers>=4.40
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest; extra == 'test'
27
+ Description-Content-Type: text/markdown
28
+
29
+ # inaVAMOS: Voice And Music Open Segmenter
30
+
31
+ Speech (voice activity) and music detection for audio and video files, based on
32
+ self-supervised (SSL) models from [INA](https://www.ina.fr).
33
+
34
+ `inaVAMOS` splits an audio stream into homogeneous segments labelled
35
+ `speech`, `music`, `speech+music` or `other`. It wraps two models published on the
36
+ HuggingFace Hub:
37
+
38
+ | Detector | Model | Task |
39
+ |----------|-------|------|
40
+ | `speech` | [ina-foss/ssl-vad-music2vec](https://huggingface.co/ina-foss/ssl-vad-music2vec) | Voice activity detection (VAD) |
41
+ | `music` | [ina-foss/ssl-music-detection-music2vec](https://huggingface.co/ina-foss/ssl-music-detection-music2vec) | Music detection |
42
+
43
+ Both models use the CNN and the first transformer layer of the
44
+ [music2vec](https://huggingface.co/m-a-p/music2vec-v1) SSL encoder, followed by an MLP
45
+ classifier and Viterbi smoothing. They share the same encoder, which is computed only
46
+ once when both detectors are used.
47
+
48
+ ### Output labels
49
+
50
+ The two detectors make independent decisions every 20 ms, which are combined into
51
+ a single timeline:
52
+
53
+ | speech | music | label |
54
+ |--------|-------|-------|
55
+ | yes | no | `speech` |
56
+ | no | yes | `music` |
57
+ | yes | yes | `speech+music` |
58
+ | no | no | `other` |
59
+
60
+ `other` covers everything that is neither speech nor music: silence, background
61
+ noise, applause, sound effects... When a single detector is run, `other` means "not
62
+ detected" by that detector: with `-d speech`, it is non-speech and can include
63
+ music; with `-d music`, it is non-music and can include speech.
64
+
65
+ The segments of each detector are also available separately (see
66
+ [Python usage](#python-usage), and the `json` and `textgrid` output formats).
67
+
68
+ ## Installation
69
+
70
+ ```bash
71
+ pip install inaVAMOS
72
+ ```
73
+
74
+ The development version can be installed with
75
+ `pip install git+https://github.com/ina-foss/inaVAMOS.git`.
76
+
77
+ [ffmpeg](https://ffmpeg.org) is recommended to read any audio or video format
78
+ (`apt install ffmpeg`, `brew install ffmpeg` or `conda install ffmpeg`). Without it,
79
+ files are read with [librosa](https://librosa.org) (wav, flac, ogg, mp3…).
80
+
81
+ To use a GPU, install the [PyTorch build](https://pytorch.org/get-started/locally/)
82
+ matching your CUDA version before installing `inaVAMOS`.
83
+
84
+ The models (about 80 MB) are downloaded from the HuggingFace Hub on first use and
85
+ cached. Afterwards, `HF_HUB_OFFLINE=1` can be set to work offline.
86
+
87
+ ## Command line usage
88
+
89
+ ```bash
90
+ # Print the segmentation of a file as CSV
91
+ ina-vamos -i media.mp3
92
+
93
+ # Process several files and write one result per file in a directory
94
+ ina-vamos -i *.mp4 -o results/ -f textgrid
95
+
96
+ # Voice activity detection only, on a GPU, on the first 10 minutes
97
+ ina-vamos -i media.wav -d speech --device cuda --stop 600
98
+ ```
99
+
100
+ Output example (CSV):
101
+
102
+ ```
103
+ label,start,stop
104
+ music,0.000,23.900
105
+ other,23.900,32.060
106
+ ...
107
+ speech,63.380,65.300
108
+ other,65.300,65.980
109
+ speech,65.980,68.200
110
+ ```
111
+
112
+ Main options (see `ina-vamos --help`):
113
+
114
+ | Option | Description |
115
+ |--------|-------------|
116
+ | `-i` | input files, in any format readable by ffmpeg |
117
+ | `-o` | output directory (default: standard output). Existing results are skipped unless `--overwrite` is given, so interrupted batches can be resumed |
118
+ | `-f` | output format: `csv`, `tsv`, `json`, `textgrid` (Praat) or `audacity` (label track) |
119
+ | `-d` | detectors to run: `speech` and/or `music` (default: both) |
120
+ | `--device` | `cpu`, `cuda`, `cuda:1`… (default: GPU if available) |
121
+ | `--start`, `--stop` | process only a portion of the files (seconds) |
122
+
123
+ `python -m inavamos` is equivalent to `ina-vamos`.
124
+
125
+ ## Python usage
126
+
127
+ ```python
128
+ from inavamos import Segmenter
129
+
130
+ seg = Segmenter() # or Segmenter(detectors=["speech"]), Segmenter(device="cuda")...
131
+
132
+ # Combined timeline: a list of (label, start, stop) tuples covering the whole file
133
+ for label, start, stop in seg("media.mp3"):
134
+ print(label, start, stop)
135
+ ```
136
+
137
+ `Segmenter.process` returns a `Result` object with more detailed outputs:
138
+
139
+ ```python
140
+ result = seg.process("media.mp3", start=60, stop=120)
141
+
142
+ result.segments("speech") # [Segment(label='speech', start=63.38, stop=65.3), ...]
143
+ result.segments("music") # segments where music is detected
144
+ result.timeline() # combined timeline, as returned by seg("media.mp3")
145
+ result.probabilities["music"] # frame-level probabilities (numpy array, one frame every 20 ms)
146
+ result.decisions["music"] # frame-level boolean decisions after Viterbi smoothing
147
+ result.frame_duration # 0.02
148
+ ```
149
+
150
+ Signals can also be given directly, as 1-D numpy arrays or torch tensors:
151
+
152
+ ```python
153
+ import librosa
154
+
155
+ audio, sr = librosa.load("media.wav", sr=16000)
156
+ result = seg.process(audio, sampling_rate=sr)
157
+ ```
158
+
159
+ Results can be exported with `inavamos.export.export(result, "textgrid")`.
160
+
161
+ ### Options
162
+
163
+ | Argument | Default | Description |
164
+ |----------|---------|-------------|
165
+ | `detectors` | `("speech", "music")` | detectors to run |
166
+ | `device` | GPU if available | torch device |
167
+ | `window_duration` | `30.0` | audio is processed by overlapping windows of this duration (seconds), matching the slices used to train the models. `None` processes a signal at once, like the code published on the model cards; memory then grows quadratically with the duration |
168
+ | `context_duration` | `2.5` | overlap on each side of the windows (seconds) |
169
+ | `batch_size` | `8` | number of windows processed together |
170
+ | `transitions` | `{"speech": 0.99, "music": 0.95}` | Viterbi self-transition probabilities. Higher values produce fewer, longer segments |
171
+ | `token` | `None` | HuggingFace token, only needed for private repositories |
172
+ | `revision` | `None` | model revision on the Hub (branch, tag or commit), to pin a version |
173
+ | `repo_ids` | `None` | alternative model repositories or local directories, e.g. `{"speech": "/models/ssl-vad-music2vec"}` |
174
+
175
+ ## Performance
176
+
177
+ About 30× faster than real time on a laptop CPU (an hour of audio in about 2 minutes),
178
+ and much faster on a GPU.
179
+
180
+ ## Development
181
+
182
+ ```bash
183
+ pip install -e ".[test]"
184
+ pytest # all tests (downloads the models on first run)
185
+ pytest -m "not models" # unit tests only, without the models
186
+ ```
187
+
188
+ The `models` tests check, among others, that the output is identical to the
189
+ reference code published on the model cards.
190
+
191
+ To release a new version: update `__version__` in `src/inavamos/__init__.py`, then
192
+ publish a GitHub release tagged `v<version>` (e.g. `v0.2.0`). The
193
+ [publish workflow](https://github.com/ina-foss/inaVAMOS/blob/main/.github/workflows/publish.yml) runs the tests, builds the package
194
+ and uploads it to PyPI.
195
+
196
+ ## License and citation
197
+
198
+ inaVAMOS and the models it uses are distributed under the Pantagruel Research-only
199
+ License ([French version](https://github.com/ina-foss/inaVAMOS/blob/main/LICENSE.md), which prevails, and
200
+ [unofficial English translation](https://github.com/ina-foss/inaVAMOS/blob/main/LICENSE.en.md)). It restricts their use to
201
+ non-commercial research and development activities, by research organisations and
202
+ heritage institutions (libraries, museums, archives, audiovisual heritage). For any
203
+ other use, contact the Pantagruel Consortium at pantagruel-licence@univ-grenoble-alpes.fr.
204
+
205
+ If you use this tool or the models, please cite:
206
+
207
+ ```bibtex
208
+ @inproceedings{pelloin2026lrec,
209
+ author = "Pelloin, Valentin and Bekkali, Lina and Dehak, Reda and Doukhan, David",
210
+ year = "2026",
211
+ title = "Data Selection Effects on Self-Supervised Learning of Audio Representations for French Audiovisual Broadcasts",
212
+ booktitle = "Fifteenth International Conference on Language Resources and Evaluation (LREC 2026)",
213
+ address = "Palma, Mallorca, Spain",
214
+ publisher = "European Language Resources Association",
215
+ }
216
+ ```