Interfejs systemu rozpoznawania mowy Sarmata. Więcej...

Statyczne metody publiczne
static int	Init (string sqlitePath)
	Konfiguracja intefejsu. Funkcję należy wywołać przy pierwszym użyciu interfejsu, np. przy załadowaniu biblioteki. Przyjmuje ścieżkę dostępu do pliku bazy danych SQLite. Sprawdza poprawność zawartości pliku. Jeśli podany plik nie istnieje, zostanie utworzony. W przypadku problemów np. z prawami dostępu - funkcja zwróci -1.
static int	CreateDictionary (int dictionaryId, string[] words)
	Tworzy słownik o podanym identyfikatorze i zapisuje dane w SQLite. Słowa/frazy znajdują się w zmiennej words (każda fraza w oddzielnej komórce tablicy). Wszystkie liczby które mają być rozpoznawane muszą także znaleźć się w zmiennej words. Przykładowy słownik: string[] dictWords = new string[] {"rozpoznawanie mowy", "ala", "ma", "kota", "1", "2", "3", "10"}; (jedna fraza, trzy wyrazy, cztery liczby). Jeśli słownik o danym identyfikatorze istnieje już w bazie - sprawdzana jest zawartość słownika. Jeśli dane są identyczne to słownik pozostaje w bazie, jeśli się różnią - to generowany jest nowy slownik. Dla porównania zawartości słowników nie ma znaczenia kolejność wyrazów (są porównywane jako zbiory). Jeśli dane się różnią - to poprzednia zawartość jest kasowana, a na jej miejsce generowane są słowa z nowego słownika.
static int	RemoveDictionary (int dictionaryId)
	Usunięcie zawartości słownika z bazy SQLite. W przypadku próby usunięcia nieznanego słownika, funkcja zwróci kod błędu.
static int[]	GetDictionaries ()
	Pobranie listy identyfikatorów słowników przechowywanych w SQLite.
static int	CreateSession ()
	Metoda alokuje potrzebną pamięć dla sesji. Tworzy wewnętrzne obiekty wykorzystywane, na potrzeby interfejsu, do rozpoznawania mowy.
static int	Recognize (int sessionId, short[] samples)
	Główna funkcja interfejsu rozpoznawania mowy SARMATA. Działa w kontekście sesji (sessionID), przyjmuje próbki (format: liniowe PCM, bez kompresji, 16kHz), dokonuje detekcji mowy i w przypadku wykrycia słów zapisuje wyniki (dołącza do poprzednich danych, jeśli dla tej sesji są już dostępne wyniki). Jeśli po przekroczeniu ustalonych limitów czasowych (ilości próbek) nie zostanie wykryta mowa (NoInputTimeout) lub zrealizowane dopasowanie do słownika (MaxSpeechTimeout) zwraca odpowiedni kod błędu. Parametry można ustalić poprzez ConfigureSession().
static string	GetRecognition (int sessionId)
	Pobranie rozpoznanych słów dla wybranej sesji oraz oceny ich pewności. Słowa/frazy dostępne są w formacie word#score, gdzie word jest rozpoznaną hipotezą, a score oceną pewności rozpoznania, z zakresu 0.0 - 1.0, przy czym score == 0.0 oznacza zerową pewność, natomiast score == 1.0 - 100% pewność, że zgromadzone próbki (samples) zawierają proponowaną hipotezę. W przypadku rozpoznania wielu fraz, poszczególne rozpoznania będą rozdzielone znakiem '\|'; word1#score1\|word2#score2\|word3#score3. Pobranie wyników usuwa je z pamieci.
static int	SetDictionary (int sessionId, int dictionaryId)
	Przypisuje wybrany słownik do sesji. Dane są odczytywane z SQLite'a i kopiowane do lokalnej pamięci, co pozwala na uniknięcie konfliktów w przypadku modyfikacji / usunięcia słownika który jest używany w przynajmniej jednej sesji.
static int	CloseSession (int sessionId)
	Zwalnia pamiec i wszelkie zasoby przetrzymywane przez sesje.
static int	ConfigureSession (int sessionId, AGHSarmataConst.SessionConfigType paramName, object paramValue)
	Ustawienie parametrów rozpoznawania dla wybranej sesji. Wartość jest rzutowana na odpowiedni typ parametru. Dostępne rodzaje ustawień:

Opis szczegółowy

Interfejs systemu rozpoznawania mowy Sarmata.

Tomasz Jadczyk, jadcz.nosp@m.yk@a.nosp@m.gh.ed.nosp@m.u.pl

Dokumentacja funkcji składowych

static int AGH.DSP.SpeechRecognition.AGHSarmata.CloseSession ( int sessionId ) [static]

Zwalnia pamiec i wszelkie zasoby przetrzymywane przez sesje.

              //Dodaj potrzebne konfiguracje biblioteki (Init(...))
              int sessionID = AGHSarmata.CreateSession();
              if(sessionID != AGHSarmataConst.ERROR) {
                //......
                AGHSarmata.CloseSession(sessionID);
              }

Parametry:

sessionId Unikalny identyfikator sesji, uzyskany z metody CreateSession()

Zwraca:: AGHSarmataConst.OK jeśli zamknięcie sesji przebiegło prawidłowo; AGHSarmataConst.ERROR w przeciwnym przypadku

static int AGH.DSP.SpeechRecognition.AGHSarmata.ConfigureSession	(	int	sessionId,
		AGHSarmataConst.SessionConfigType	paramName,
		object	paramValue
	)		`[static]`

Ustawienie parametrów rozpoznawania dla wybranej sesji. Wartość jest rzutowana na odpowiedni typ parametru. Dostępne rodzaje ustawień:

paramName="NoInputTimeout", Type:Int32 - Maksymalna długość sygnału, który jest uznany za ciszę. Po przekroczeniu progu funkcja Recognize zwraca odpowiedni kod błędu. Wartość w milisekundach [ms]. Domyślnie: 10000[ms]
paramName="MaxSpeechTimeout", Type:Int32 - Maksymalna długość sygnału, któru jest rozpoznawany jako mowa. Po przekroczeniu progu, jeśli nie zostało zaakceptowane żadne dopasowanie do istniejącego słownika, funkcja Recognize zwraca odpowiedni kod błędu. Wartość w milisekundach [ms]. Domyślnie: 5000[ms]
paramName="LogFilePath", Type:String - Ścieżka do pliku w którym logowane są informacje z działania programu. Jeśli nie ustawione - informacje nie są logowane. Domyślnie: null

Parametry:

sessionId	Unikalny identyfikator sesji, uzyskany z metody CreateSession()
paramName	Nazwa parametru do ustawienia dla wybranej sesji
paramValue	Wartość parametru do ustawienia. Wartość musi być odpowiedniego typu, zgodnego z rodzajem parametru.

Zwraca:: AGHSarmataConst.OK jeśli wartość parametru została ustawiona prawidłowo ; AGHSarmataConst.ERROR w przeciwnym przypadku (np nieprawidłowy identyfikator sesji, nieprawidłowy typ wartości)

static int AGH.DSP.SpeechRecognition.AGHSarmata.CreateDictionary	(	int	dictionaryId,
		string[]	words
	)		`[static]`

Tworzy słownik o podanym identyfikatorze i zapisuje dane w SQLite. Słowa/frazy znajdują się w zmiennej words (każda fraza w oddzielnej komórce tablicy).
Wszystkie liczby które mają być rozpoznawane muszą także znaleźć się w zmiennej words.
Przykładowy słownik:

string[] dictWords = new string[] {"rozpoznawanie mowy", "ala", "ma", "kota", "1", "2", "3", "10"};

(jedna fraza, trzy wyrazy, cztery liczby).
Jeśli słownik o danym identyfikatorze istnieje już w bazie - sprawdzana jest zawartość słownika. Jeśli dane są identyczne to słownik pozostaje w bazie, jeśli się różnią - to generowany jest nowy slownik. Dla porównania zawartości słowników nie ma znaczenia kolejność wyrazów (są porównywane jako zbiory). Jeśli dane się różnią - to poprzednia zawartość jest kasowana, a na jej miejsce generowane są słowa z nowego słownika.

              string[] dictWords = new string[] {"ala", "ma", "kota", "1", "2", "3"};
              int dictionaryId = 1234; //Unikalny identyfikator słownika;
              int status = AGHSarmata.CreateDictionary(dictionaryId, dictWords);
              if(status != AGHSarmataConst.ERROR) {
                //....
              }

Parametry:

dictionaryId	identyfikator słownika
words	lista słów/fraz tworzących słownik

Zwraca:

AGHSarmataConst.OK jeśli operacja zakończy się sukcesem;
AGHSarmataConst.ERROR w przypadku wystąpienia błędu.

static int AGH.DSP.SpeechRecognition.AGHSarmata.CreateSession ( ) [static]

Metoda alokuje potrzebną pamięć dla sesji. Tworzy wewnętrzne obiekty wykorzystywane, na potrzeby interfejsu, do rozpoznawania mowy.

              //Konfiguracja parametrów biblioteki
              string sqlPath = "/home/user/sarmata/sarmataDb.sql";
              int status = AGHSarmata.Init(sqlPath);

              if(status != AGHSarmataConst.ERROR) {

                //Utwórz nową sesję
                int sessionID = AGHSarmata.CreateSession()
                if(sessionID != AGHSarmataConst.ERROR) { //Sprawdzenie czy sesja została prawidłowo utworzona
                  //....
                }
              }

Zwraca:

unikalny identyfikator sesji, będący liczbą dodatnią;
lub AGHSarmataConst.ERROR w przypadku błędu

static int [] AGH.DSP.SpeechRecognition.AGHSarmata.GetDictionaries ( ) [static]

Pobranie listy identyfikatorów słowników przechowywanych w SQLite.

              //Konfiguracja parametrów biblioteki
              string sqlPath = "/home/user/sarmata/sarmataDb.sql";
              int initStatus = AGHSarmata.Init(sqlPath);
              if(initStatus != AGHSarmataConst.ERROR) {
                int[] dictIds = AGHSarmata.GetDictionaries();
                if(dictIds != null) {
                    foreach(int dictId in dictIds) {
                        //obsługa identyfikatora słownika
                    }
                }
              }

Zwraca:

tablica dostępnych identyfikatorów słowników (może mieć długość 0 jeśli nie ma zdefiniowanych słowników);
lub null w przypadku błędu.

static string AGH.DSP.SpeechRecognition.AGHSarmata.GetRecognition ( int sessionId ) [static]

Pobranie rozpoznanych słów dla wybranej sesji oraz oceny ich pewności. Słowa/frazy dostępne są w formacie word#score, gdzie word jest rozpoznaną hipotezą, a score oceną pewności rozpoznania, z zakresu 0.0 - 1.0, przy czym score == 0.0 oznacza zerową pewność, natomiast score == 1.0 - 100% pewność, że zgromadzone próbki (samples) zawierają proponowaną hipotezę.
W przypadku rozpoznania wielu fraz, poszczególne rozpoznania będą rozdzielone znakiem '|'; word1#score1|word2#score2|word3#score3. Pobranie wyników usuwa je z pamieci.

              //Konfiguracja parametrów biblioteki
              string
              sqlPath = "/home/user/sarmata/sarmataDb.sql";
              int initStatus = AGHSarmata.Init(sqlPath);
              if(initStatus != AGHSarmataConst.ERROR) {
                //Tworzenie sesji
                int sessionID = AGHSarmata.CreateSession();
                if(sessionID != AGHSarmataConst.ERROR) {
                    int dictionaryId = 1234; //Identyfikato słownika - słownik o takim identyfikatorze musi być utworzony przed użyciem, za pomocą funkcji CreateDictionary, w przeciwnym wypadku funkcja SetDictionary zwróci kod błędu -1
                    int assignId = AGHSarmata.SetDictionary(dictionaryId, sessionID);
                    if(assignId != AGHSarmataConst.ERROR) {
                      short[] samples = readSamples(); //Akwizycja sygnału (funkcja spoza biblioteki AGHSarmata)
                      int status = AGHSarmata.Recognize(sessionID, samples); //Uruchom rozpoznawanie
                      if(status == AGHSarmataConst.RECOGNITION) { //status == AGHSarmataConst.RECOGNITION informuje o dostępności wyników
                        string recognition = AGHSarmata.GetRecognition(sessionID);
                        if(recognition != AGHSarmataConst.RECOGNITION_ERROR) { //Sprawdzenie czy nie wystąpił błąd
                          string[] wordsWithScore = recognition.Split(new Char[] { '|'}); //split "word1#score1|word2#score2|..." => wordsWithScore[0] == word1#score1; wordsWithScore[1] == word2#score2 ....
                          foreach(string wordPair in wordsWithScore) {
                            string[] wordAndScore = wordPair.Split(new Char[] { '#' }); //split "word#score" => wordAndScore[0] == word; wordAndScore[1] == score
                            float score = 0.0;
                            if( Float.TryParse( wordAndScore[1], out score) {
                                System.Console.WriteLine("Word: {0}, Score: {1}", wordAndScore[0], score);
                            }
                          }
                        }
                      }
                    }
                  //Zwolnienie zasobów
                   AGHSarmata.CloseSession(sessionID);
                }
              }

Parametry:

sessionId Unikalny identyfikator sesji, uzyskany z metody CreateSession()

Zwraca:

rozpoznane słowa/frazy w odpowiednim formacie ("word1#score1|word2#score2|...") ;
lub AGHSarmataConst.NO_RECOGNITION_STR w przypadku braku rozpoznania dla danej sesji ;
lub AGHSarmataConst.RECOGNITION_ERROR w przypadku błędu

static int AGH.DSP.SpeechRecognition.AGHSarmata.Init ( string sqlitePath ) [static]

Konfiguracja intefejsu. Funkcję należy wywołać przy pierwszym użyciu interfejsu, np. przy załadowaniu biblioteki. Przyjmuje ścieżkę dostępu do pliku bazy danych SQLite. Sprawdza poprawność zawartości pliku. Jeśli podany plik nie istnieje, zostanie utworzony. W przypadku problemów np. z prawami dostępu - funkcja zwróci -1.

              string sqlPath = "/home/user/sarmata/sarmataDb.sql";
              int status = AGHSarmata.Init(sqlPath);
              if(status != AGHSarmataConst.ERROR) {
                //uruchom rozpoznawanie
              }

Parametry:

sqlitePath

ścieżka dostępu do pliku, np.

/home/user/sarmata/sarmataDb.sql

Zwraca:

AGHSarmataConst.OK jeśli operacja zakończy się sukcesem;
AGHSarmataConst.ERROR w przypadku błędu, np. z prawami dostępu.

static int AGH.DSP.SpeechRecognition.AGHSarmata.Recognize	(	int	sessionId,
		short[]	samples
	)		`[static]`

Główna funkcja interfejsu rozpoznawania mowy SARMATA.
Działa w kontekście sesji (sessionID), przyjmuje próbki (format: liniowe PCM, bez kompresji, 16kHz), dokonuje detekcji mowy i w przypadku wykrycia słów zapisuje wyniki (dołącza do poprzednich danych, jeśli dla tej sesji są już dostępne wyniki). Jeśli po przekroczeniu ustalonych limitów czasowych (ilości próbek) nie zostanie wykryta mowa (NoInputTimeout) lub zrealizowane dopasowanie do słownika (MaxSpeechTimeout) zwraca odpowiedni kod błędu. Parametry można ustalić poprzez ConfigureSession().

              //Konfiguracja parametrów biblioteki
              string sqlPath = "/home/user/sarmata/sarmataDb.sql";
              int initStatus = AGHSarmata.Init(sqlPath);
              if(initStatus != AGHSarmataConst.ERROR) {

                //Tworzenie sesji
                int sessionID = AGHSarmata.CreateSession();
                if(sessionID != AGHSarmataConst.ERROR) {

                  //Tworzenie słownika, następnie przypisanie słownika do sesji
                  string[] dictWords = new string[] {"ala", "ma", "kota", "101", "102", "103"};
                  int dictionaryId = 1234; //identyfikator słownika
                  int dictStatus = AGHSarmata.CreateDictionary(dictionaryId, dictWords);

                  if(dictStatus != AGHSarmataConst.ERROR) {
                    //przypisanie słownika do utworzonej sesji
                    int assignStatus = AGHSarmata.SetDictionary(dictionaryId, sessionID);
                    if(assignStatus != AGHSarmataConst.ERROR) {    
                        short[] samples = readSamples(); //Akwizycja sygnału (funkcja spoza biblioteki AGHSarmata)
                        int status = AGHSarmata.Recognize(sessionID, samples); //Uruchom rozpoznanie
                        switch(status) {
                        case AGHSarmataConst.RECOGNITION:  //Rozpoznano jedno z wyrażeń dostępnych w słowniku
                            //pobierz rozpoznanie
                            string recognition = AGHSarmata.GetRecognition(sessionID);
                            // ... //wykorzystanie rozpoznanego wyrazu/frazy
                            break;
                        case AGHSarmataConst.NO_RECOGNITION:
                            //brak rozpoznania - dostarcz dodatkowe próbki sygnału, uruchom ponownie metodę Recognize
                            break;
                        case AGHSarmataConst.ERROR:
                            //Błąd działania - obsługa
                            break;
                        case ....
                        }
                    }
                  }

                  //Zwolnienie zasobów
                  AGHSarmata.CloseSession(sessionID);
                }
              }

Parametry:

sessionId	unikalny identyfikator sesji, uzyskany z metody CreateSession()
samples	tablica próbek sygnału o dowolnej długości, częstotliwość próbkowania 16kHz, liczby 16-bitowe ze znakiem

Zwraca:

AGHSarmataConst.RECOGNITION jesli rozpoznanie jest gotowe;
AGHSarmataConst.NO_RECOGNITION w przypadku braku rozpoznania;
AGHSarmataConst.ERROR w przypadku wystąpienia błędu dzialania;
AGHSarmataConst.NOINPUT_TIMEOUT Przekroczono czas maksymalnego oczekiwania na mowę (NoInputTimeout). 'Czas' oznacza ilość próbek przekazanych do sesji;
AGHSarmataConst.MAXSPEECH_TIMEOUT Przekroczono czas maksymalnego dopasowania mowy. (MaxSpeechTimeout). 'Czas' oznacza ilość próbek przekazanych do sesji.

Jeśli dla danej sesji rozpoznanie jest gotowe i zostanie wywołana metoda Recognize() (przed pobraniem wyników metodą GetRecognition()), kolejne wywołania metody Recognize zwróca wynik '0' pomimo aktualnie dostępnego wyniku, do momentu wykrycia następnego słowa.

static int AGH.DSP.SpeechRecognition.AGHSarmata.RemoveDictionary ( int dictionaryId ) [static]

Usunięcie zawartości słownika z bazy SQLite. W przypadku próby usunięcia nieznanego słownika, funkcja zwróci kod błędu.

Parametry:

dictionaryId identyfikator słownika do usunięcia.

              //Konfiguracja parametrów biblioteki
              string sqlPath = "/home/user/sarmata/sarmataDb.sql";
              int initStatus = AGHSarmata.Init(sqlPath);
              if(initStatus != AGHSarmataConst.ERROR) {
                string[] dictWords = new string[] {"ala", "ma", "kota", "102"};
                int dictionaryId = 1234; //Unikalny identyfikator słownika
                int status = AGHSarmata.CreateDictionary(dictionaryId, dictWords);
                if(status != AGHSarmataConst.ERROR) {
                    //....

                    //Usunięcie z bazy danych słownika, który nie będzie więcej wykorzystywany
                    int dictRemStatus = AGHSarmata.RemoveDictionary(dictionaryId);
                    if(dictRemStatus == AGHSarmataConst.ERROR) {
                        //... Obsługa błędu
                    }
                }
              }

Zwraca:

AGHSarmataConst.OK jeśli operacja zakończy się sukcesem;
AGHSarmataConst.ERROR w przypadku wystąpienia błędu.

static int AGH.DSP.SpeechRecognition.AGHSarmata.SetDictionary	(	int	sessionId,
		int	dictionaryId
	)		`[static]`

Przypisuje wybrany słownik do sesji. Dane są odczytywane z SQLite'a i kopiowane do lokalnej pamięci, co pozwala na uniknięcie konfliktów w przypadku modyfikacji / usunięcia słownika który jest używany w przynajmniej jednej sesji.

              //Konfiguracja parametrów biblioteki
              string sqlPath = "/home/user/sarmata/sarmataDb.sql";
              int initStatus = AGHSarmata.Init(sqlPath);
              if(initStatus != AGHSarmataConst.ERROR) {
                //Tworzenie sesji
                int sessionID = AGHSarmata.CreateSession();
                if(sessionID != AGHSarmataConst.ERROR) {
                    //Tworzenie słownika
                    string[] dictWords = new string[] {"ala", "ma", "kota", "101", "102", "103"};
                    int dictionaryId = 1234; //unikalny identyfikator słownika;
                    int dictStatus = AGHSarmata.CreateDictionary(dictionaryId, dictWords);

                    if(dictStatus != AGHSarmataConst.ERROR) {
                        //Przypisanie słownika do sesji
                        int assignStatus = AGHSarmata.SetDictionary(sessionID, dictionaryId);
                        if(assignStatus != AGHSarmataConst.ERROR) {
                            // .... Uruchom rozpoznawanie
                        }
                    }
                    //Zwolnienie zasobów
                    AGHSarmata.CloseSession(sessionID);
                }
              }

Parametry:

sessionId	Unikalny identyfikator sesji, uzyskany z metody CreateSession()
dictionaryId	Identyfikator slownika. Słownik przed użyciem w tej metodzie musi zostać utworzony przy użyciu CreateDictionary. Jednokrotne utworzenie słownika jest trwałe (zapis w bazie SQLite), pomiędzy kolejnymi użyciami AGHSarmata.

Zwraca:

AGHSarmataConst.OK jeśli operacja zakończy się sukcesem;
AGHSarmataConst.ERROR w przypadku błędu.

Dokumentacja dla tej klasy została wygenerowana z plików:

AGHSarmataAddOns.cs
AGHSarmataDictionaries.cs
AGHSarmataSessions.cs

Statyczne metody publiczne

Opis szczegółowy

Dokumentacja funkcji składowych