Własne pakiety dźwięków — jak zbudować i zaimportować własne

Vigilant Ear może nauczyć się nowych dźwięków. Własny pakiet dźwięków uczy aplikację rozpoznawać dźwięki, których nie zna wbudowany detektor Apple. Twoje lokalne ptaki, konkretna maszyna w pracy, dziwny brzęczyk na korytarzu budynku. Trenujesz mały model na Macu (bez pisania kodu), pakujesz go zipem z dwoma małymi plikami tekstowymi i importujesz na iPhonie.

Własne pakiety dokładają się do wbudowanego detektora, na wierzch. Włączenie pakietu nigdy nie wyłącza niczego innego. Syreny, alarmy i każdy inny dźwięk bezpieczeństwa działają dokładnie tak jak wcześniej.

Potrzebujesz: Maca z aplikacją Create ML z Xcode (za darmo), nagrań audio twoich dźwięków i Power Pack+ na iPhonie (darmowa próba się liczy).

Twarde wymagania — zrób to dokładnie tak

Pakiet, który pominie którykolwiek z tych punktów, zaimportuje się, ale będzie działał źle (ciągłe fałszywe alerty albo nic nie wykryte). To nie są sugestie:

1. Dodaj klasę Background. To obowiązek, nie opcja. Model musi mieć klasę wytrenowaną na twoich prawdziwych otoczeniach (cichy pokój, ulica, włączony wentylator). Wypełnij ją 15+ prawdziwymi nagraniami i oznacz ją w profiles.json przez "category": "ignored" i "threshold": 1.1. Bez klasy Background pakiet będzie odpalał alerty na ciszę bez przerwy. Klasyfikator dźwięku musi wybrać jedną ze swoich klas w każdej chwili audio. Bez koszyka „żadne z tych” oznacza cichy pokój tym, co najbardziej przypomina.
2. Wytnij ciszę z klipów treningowych. Klip z etykietą „Owl”, który ma 20 sekund ciszy i jedno pohukiwanie, uczy model, że cisza to sowa. Przytnij klipy ciasno do dźwięku docelowego. Inaczej model uczy się przerw.
3. Nazwij plik modelu dokładnie model.mlmodel albo model.mlpackage. Inna nazwa → import się nie udaje.
4. Użyj modelu Create ML Sound Classification. Modele obrazu, tekstu i tabel są odrzucane.
5. Klucze w profiles.json muszą dokładnie zgadzać się z etykietami klas modelu. Czyli z nazwami folderów treningowych, razem z wielkością liter i podkreśleniami.
6. Dodaj gateClasses (niżej). Bez tego muzyka i TV będą odpalać pakiet. To największa kontrola fałszywych alertów.
7. Spakuj pliki na najwyższym poziomie (albo w jednym folderze, nie głębiej). pack.json musi dać się znaleźć.
8. Wyrównaj klasy. Nie dawaj jednej klasie 100 klipów, a drugiej 10. Model przechyli się w stronę tej większej. Przytnij klasy z dużą liczbą nagrań, żeby liczebności były w granicach około 3× jedna wobec drugiej.

Dalej ten przewodnik przechodzi przez każdy z tych punktów, po kolei.

Krok 1 — Zbierz audio do treningu

Zrób folder na każdy dźwięk, który ma być rozpoznany. Nazwij go tym dźwiękiem i wypełnij przykładowymi nagraniami:

TrainingData/
  Mourning_Dove/        ← 20+ clips of mourning doves
  House_Finch/          ← 20+ clips of house finches
  Background/           ← 20+ clips of your ambient environment WITHOUT the sounds

Wskazówki, które naprawdę robią różnicę:

• Zawsze dodawaj klasę Background. Model musi oznaczyć każdą chwilę audio jako coś. Bez klasy tła cisza i szum ulicy wpadają do twoich prawdziwych klas i zobaczysz fałszywe alerty. Nagrywaj miejsca, w których naprawdę użyjesz pakietu: podwórko, hala, kuchnia.
• Nazwy folderów stają się etykietami, które pokazuje aplikacja (podkreślenia zamieniają się w spacje: Mourning_Dove → „Mourning Dove”). Później możesz nadpisać nazwy wyświetlane w profiles.json.
• Większa różnorodność bije większą długość: różne odległości, pory dnia i warunki tła. Klipy po kilka sekund są w porządku.
• Zwykłe formaty działają (.m4a, .wav, .mp3, .aiff).

Krok 2 — Wytrenuj model w Create ML

1. Otwórz Create ML (na Macu z Xcode: menu Xcode → Open Developer Tool → Create ML) i utwórz nowy projekt Sound Classification.
2. Przeciągnij folder TrainingData do Training Data.
3. Kliknij Train. Kilka setek klipów kończy trening w kilka minut.
4. Sprawdź kartę dokładności. Jeśli jedna klasa wypada słabo, potrzebuje więcej klipów albo bardziej różnorodnych.
5. Na karcie Output kliknij Get i zapisz model jako model.mlmodel (albo model.mlpackage — oba działają). Nazwa pliku musi być dokładnie model.mlmodel albo model.mlpackage.

Krok 3 — Napisz pack.json

Mały manifest, który opisuje pakiet:

{
  "id": "com.example.pack.socalbirds",
  "name": "SoCal Birder's Companion",
  "version": "1.0",
  "author": "Your Name",
  "classes": ["Mourning_Dove", "House_Finch", "Background"],
  "gateClasses": ["bird", "bird_vocalization", "bird_chirp_tweet", "pigeon_dove_coo", "crow_caw"]
}

• name jest wymagane. To nazwa na liście pakietów w aplikacji.
• id identyfikuje pakiet przy aktualizacjach. Ponowny import pakietu z tym samym id podmienia starą wersję w miejscu. Wystarczy dowolny unikalny ciąg w stylu reverse-DNS.
• classes to tylko dokumentacja. Aplikacja czyta prawdziwą listę klas z samego modelu, więc rozjazd niczego nie psuje (jest tylko notatka w logu).
• gateClasses (opcjonalne, mocno zalecane) to najskuteczniejsze narzędzie przeciw fałszywym trafieniom. Niżej.

gateClasses — niech model Apple będzie bramkarzem

Twój model to specjalista. Dobrze mówi, który z twoich dźwięków słyszy, ale nie wie, czym jest „żaden z moich dźwięków” (od tego jest klasa Background). Wbudowany klasyfikator Apple to klasyfikator ogólny, wytrenowany na około 300 codziennych dźwiękach. Bardzo dobrze odpowiada na grube pytanie „czy w ogóle jest tu ptak?”.

gateClasses spina je w łańcuch: wykrycia twojego pakietu pojawiają się tylko wtedy, gdy model Apple w tym samym momencie słyszy jedną z wymienionych wbudowanych kategorii. Pakiet ptaków stawia bramkę na etykietach ptaków Apple. Jeśli Apple nie uważa, że jest ptak, twój pakiet milczy. Nieważne, jak bardzo jest pewny. Ta jedna linia usuwa ogromną większość fałszywych alertów od muzyki, TV i cichego pokoju, bo model Apple punktuje je daleko poniżej bramki. Pomiń to, a pakiet działa bez bramki (w porządku do testów, gadatliwy w prawdziwym świecie).

Bramka jest dostępna tylko wtedy, gdy Apple ma już kategorię bliską twojemu dźwiękowi. Jeśli pakiet jest po coś, czego model Apple z około 300 klas nie zna (konkretna maszyna w fabryce, pik urządzenia medycznego, własny dzwonek), nie ma wbudowanej etykiety do bramki. Zostawiasz gateClasses puste i pakiet działa bez bramki. Tak ma być. To nie błąd. W takich pakietach klasa Background przestaje być jedną z kilku obron i staje się jedyną rzeczą, która stoi między tobą a ciągłymi fałszywymi alertami. Włóż w nią dużo pracy (dużo prawdziwych nagrań otoczenia) i podnieś progi poszczególnych klas.

Bramkuj pakiet ptaków na ogólnych etykietach ptaków Apple plus na tych konkretnych, które twój model naprawdę potrafi nazwać: bird, fowl, bird_vocalization, bird_chirp_tweet, bird_squawk, bird_flapping. A jeśli pakiet ma pasujący gatunek, też crow_caw i pigeon_dove_coo. Inne typy pakietów biorą własne bramki z pełnej listy wbudowanych identyfikatorów dźwięków w dodatku niżej. Na przykład pakiet ras psów stawia bramkę na dog_bark/dog_howl, pakiet pojazdów na engine/truck.

muteClasses — ustąp Apple przy dźwiękach, których twój model nie nazywa

gateClasses otwiera pakiet, gdy Apple uważa, że jest ptak. Ale Apple potrafi konkretnie nazwać niektóre ptaki, których twój model może nie obejmować: kaczkę, gęś, sowę, indyka, kurę albo koguta. Jeśli Apple słyszy kaczkę, a pakiet nie ma klasy kaczki, model na siłę wrzuci to kwakanie w najbliższy gatunek i z dużą pewnością nazwie złego ptaka. To pomyłka identyfikacji, nie fałszywy alert z ciszy. Samo gateClasses tego nie zatrzyma, bo kaczka też włącza ogólną bramkę bird.

muteClasses to naprawia: gdy Apple jest pewny jednej z tych etykiet, twój pakiet w tej chwili milczy i ustępuje konkretnemu wskazaniu Apple. Wypisz wbudowane etykiety dźwięków, których nie pokrywasz:

"muteClasses": ["owl_hoot", "duck_quack", "goose_honk", "turkey_gobble", "chicken", "chicken_cluck", "rooster_crow"]

Zasada: konkretna etykieta ptaka Apple idzie do gateClasses, jeśli model ma dla niej pasującą (albo lepszą) klasę, i do muteClasses, jeśli nie ma. Wszystko, co Apple potrafi nazwać, a ty nie → wycisz to i niech Apple ma rację.

Krok 4 — Napisz profiles.json (opcjonalnie, zalecane)

To steruje tym, jak każdy dźwięk wygląda i jak się czuje w aplikacji. Jeden wpis na klasę. Klucz to dokładna nazwa folderu albo etykiety:

{
  "Mourning_Dove": {
    "displayName": "Mourning Dove",
    "hapticCount": 1,
    "emergencyTier": "none",
    "category": "animal",
    "icon": "bird",
    "color": "teal",
    "threshold": 0.5,
    "maxRange": 150
  },
  "House_Finch": {
    "displayName": "House Finch",
    "hapticCount": 1,
    "category": "animal",
    "icon": "bird"
  },
  "Background": {
    "category": "ignored",
    "threshold": 1.1
  }
}

Każdy klucz jest opcjonalny. Pomiń cokolwiek, a wejdzie rozsądna wartość domyślna:

Klasa Background potrzebuje specjalnego wpisu pokazanego wyżej. "threshold": 1.1 sprawia, że nie da się jej zgłosić (pewność nigdy nie przekracza 1.0). Po cichu wchłania audio otoczenia i nigdy nie pojawia się jako wykrycie. Nie pomijaj jej. Klasa, której nie ma na liście, i tak dostaje domyślny próg 0.5 i pojawiłaby się w aplikacji jako ogólny dźwięk.

Krok 5 — Spakuj zip

Zaznacz trzy pliki — pack.json, profiles.json, model.mlmodel — kliknij prawym przyciskiem i wybierz Kompresuj. Spakowanie folderu, w którym leżą, też działa. Aplikacja zagląda jeden folder w głąb.

MyPack.zip
├── pack.json
├── profiles.json
└── model.mlmodel

Przenieś zip na iPhone’a, jak chcesz: AirDrop, iCloud Drive, Poczta, Wiadomości.

Krok 6 — Import na iPhonie

1. Otwórz Vigilant Ear → menu zębatki → Power Pack+.
2. Przewiń do Własne pakiety dźwięków (BYOM) i stuknij Importuj własny pakiet (.zip).
3. Wybierz zip w przeglądarce Plików.

Pakiet pojawia się na liście z liczbą dźwięków, już NA ŻYWO. Stąd możesz:

• NA ŻYWO / OFF — włączasz i wyłączasz pakiet bez kasowania. OFF nie zużywa baterii.
• Usuń — startuje 5-sekundowe odliczanie (stuknij jeszcze raz, żeby anulować), potem usuwa pakiet całkowicie.
• Importuj tyle pakietów, ile chcesz. Wszystkie działają obok wbudowanego detektora. Każdy dodatkowy pakiet na żywo kosztuje trochę baterii, więc wyłącz pakiety, których nie używasz.

Wykryte dźwięki wyglądają jak każde inne: kropka na mapie z twoją ikoną i kolorem, nazwa wyświetlana w alertach i ustawiona haptyka.

Kilka wbudowanych zachowań, które warto znać: aplikacja nie przekazuje wykryć z własnych pakietów do peerów mesh Constellation (na innych telefonach nie ma twojego pakietu), a dźwięki pakietu potrzebują dwóch wykryć z rzędu, zanim pojawi się alert. To odcina fałszywe trafienia z jednej klatki.

Rozwiązywanie problemów

Aktualizacja pakietu

Wytrenuj jeszcze raz albo edytuj, spakuj od nowa i zaimportuj ponownie z tym samym id w pack.json. Aplikacja podmienia starą wersję w miejscu.

Appendix: Built-in Sound Identifiers (iOS 26.5)

To wbudowane kategorie dźwięków, które rozpoznaje klasyfikator Sound Analysis Apple na urządzeniu. Te etykiety są dostępne wyżej dla gateClasses i muteClasses. Apple nie publikuje już tej listy na stronie dla deweloperów, więc tabelę niżej odczytano wprost z klasyfikatora na urządzeniu (SNClassifierIdentifier.version1).

Znane klasyfikacje na lipiec 2026 (iOS 26.5): 303 etykiety. Apple może dodać, usunąć albo zmienić nazwę w każdej aktualizacji systemu. Traktuj to jako zdjęcie z jednej chwili. Bramka na etykiecie, którą przyszły system usunie, po prostu nigdy nie zadziała (pakiet milczy). Nowo dodana etykieta nie istnieje, dopóki na niej nie zrobisz bramki. Użyj dokładnie takiej pisowni, jaka jest w tabeli (małe litery, podkreślenia).

© 2026 Wingdings, Inc.
Wszelkie prawa zastrzeżone.
Wiele patentów w toku