{"id":16256451,"url":"https://github.com/masyagin1998/hsv","last_synced_at":"2025-07-23T20:03:12.608Z","repository":{"id":37656055,"uuid":"268221044","full_name":"masyagin1998/HSV","owner":"masyagin1998","description":"Hubbub Suppression for Voice","archived":false,"fork":false,"pushed_at":"2024-01-19T16:56:25.000Z","size":30391,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-20T09:45:17.744Z","etag":null,"topics":["diploma","ffmpeg","hsv","noise-suppression","patch","spectral-subtraction","speech-enhancement","wiener-filtering"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/masyagin1998.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-31T06:16:37.000Z","updated_at":"2024-01-19T16:56:22.000Z","dependencies_parsed_at":"2024-10-27T21:36:04.866Z","dependency_job_id":"8f03847f-8741-4001-8504-761d3750f4f7","html_url":"https://github.com/masyagin1998/HSV","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/masyagin1998/HSV","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masyagin1998%2FHSV","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masyagin1998%2FHSV/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masyagin1998%2FHSV/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masyagin1998%2FHSV/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/masyagin1998","download_url":"https://codeload.github.com/masyagin1998/HSV/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masyagin1998%2FHSV/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266738657,"owners_count":23976439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diploma","ffmpeg","hsv","noise-suppression","patch","spectral-subtraction","speech-enhancement","wiener-filtering"],"created_at":"2024-10-10T15:45:15.417Z","updated_at":"2025-07-23T20:03:12.588Z","avatar_url":"https://github.com/masyagin1998.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HSV\n\n\u003cimg src=\"https://github.com/masyagin1998/HSV/blob/master/docs/pics/logo.png\" height=\"150\" width=\"150\"\u003e\n\n**HSV** is a **H**ubbub **S**uppression for **V**oice tool, written in pure C.\n\n## Техническая информация\n\n**HSV** - это библиотека шумоочистки/улучшения голоса в реальном времени, написанная без зависимостей на чистом [C99](https://en.cppreference.com/) и легко встраиваемая в [FFmpeg](https://ffmpeg.org/) и [MPV](https://mpv.io/). Она является моей выпускной квалификационной работой с кафедры \"Теоретической информатики и компьютерных технологий\" [МГТУ им Н. Э. Баумана.](https://bmstu.ru/)\n\nБиблиотека **HSV** предоставляет блочно-последовательную обработку звуковых данных через внутренний кольцевой буфер. Для детектирования шума используется алгоритм `MCRA-2` Лойзю-Рангачари, для непосредственной шумоочистки могут быть использованы алгоритм спектрального вычитания Берути-Шварца или различные модификации алгоритма винеровской фильтрации Скалара. Для вычисления дискретного преобразования Фурье и обратного дискретного преобразования Фурье используются алгоритмы Кули-Тьюки и Блюштейна.\n\n## Установка и запуск HSV\n\nДля сборки и запуска библиотеки **HSV** необходимы  `С99`-совместимый компилятор, утилита [Make](https://www.gnu.org/software/make/) и `unix`-совместимая ОС.\nБиблиотека **HSV** может быть легко перенесена на [C89](https://en.cppreference.com/), для этого необходимо лишь реализвовать некоторые библиотечные функции [\u003cmath.h\u003e](https://www.gnu.org/software/libc/manual/html_node/Mathematics.html), добавленные в стандарте `C99`. Обратная совместимость обеспечивается объявлением всех переменных строго в начале блоков и использованием только \"классических\" типов данных.\n\nДля сборки **HSV** и тестового примера необходимо выполнить следующую последовательность команд:\n\n```sh\n$ git clone https://github.com/masyagin1998/HSV.git\n$ cd HSV\n$ make\n```\n\nЧтобы не увеличивать и без того немалый объем кода алгоритмами работы с `wav`, параметры входных и выходных `wav`-файлов строго задаются в примере `examples/example.c`.\n\nЗапуск тестового примера осуществляется следующим образом:\n\n```sh\n$ ./bin/example --wiener examples/in.wav examples/out.wav\n```\n\nгде `--wiener` - один из видов алгоритмов шумоподавления;\n`examples/in.wav` - входной `wav`-файл;\n`examples/out.wav` - выходной `wav`-файл;\n\n## Встраивание в FFmpeg\n\nНа сегодяшний день `FFmpeg` является одной из наиболее активно используемых библиотек для обработки аудио- и видеопотоков в реальном времени. На данный момент в ней отсутствуют методы для непосредственного подавления шума/улучшения голоса, поэтому было решено встроить в неё **HSV**.\n\nЧтобы собрать `FFmpeg` с поддержкой **HSV** необходимо выполнить следующие шаги:\n\n- скачать зависимости для сборки `FFmpeg`:\n```sh\n$ sudo apt-get update -qq \u0026\u0026 sudo apt-get -y install autoconf automake build-essential cmake git-core \\\n$ libass-dev libfreetype6-dev libgnutls28-dev libsdl2-dev libtool libva-dev libvdpau-dev libvorbis-dev \\\n$ libxcb1-dev libxcb-shm0-dev libxcb-xfixes0-dev pkg-config texinfo wget yasm zlib1g-dev\n```\n\n- создать папки для сборки `FFmpeg`:\n```sh\n$ mkdir -p ~/ffmpeg_sources ~/bin\n```\n\n- скачать архив с исходным кодом `FFmpeg` и распаковать его:\n```sh\n$ cd ~/ffmpeg_sources\n$ wget -O ffmpeg-snapshot.tar.bz2 https://ffmpeg.org/releases/ffmpeg-snapshot.tar.bz2\n$ tar xjvf ffmpeg-snapshot.tar.bz2\n```\n\n- применить патч `hsvden.patch` из папки `HSV/ffmpeg/patches` или добавить/заменить файлы исходного кода `FFmpeg` файлами из `HSV/ffmpeg/src`:\n```sh\n$ cp -r HSV/ffmpeg/* ~/ffmpeg_sources\n$ ./apply_patches.sh\n```\n\n- выполнить сборку \"пропатченного\" `FFmpeg` (возможно, Вам придётся отключить `gnutls` и `libaom`):\n```sh\n$ cd ffmpeg\n$ PATH=\"$HOME/bin:$PATH\" PKG_CONFIG_PATH=\"$HOME/ffmpeg_build/lib/pkgconfig\" ./configure --prefix=\"$HOME/ffmpeg_build\" \\\n$ --pkg-config-flags=\"--static\" --extra-cflags=\"-I$HOME/ffmpeg_build/include\" --extra-ldflags=\"-L$HOME/ffmpeg_build/lib\" \\\n$ --extra-libs=\"-lpthread -lm\"  --bindir=\"$HOME/bin\" --enable-gpl --enable-gnutls --enable-libaom --enable-libass \\\n$ --enable-libfdk-aac --enable-libfreetype --enable-libmp3lame --enable-libopus --enable-libvorbis --enable-nonfree\n$ PATH=\"$HOME/bin:$PATH\" make -j8\n$ make install -j8\n```\n\n- после этого в папке `~/bin` должна появиться сборка `FFmpeg` с поддержкой библиотеки `HSV`. Для запуска `FFmpeg` с одним из фильтров `HSV` необходимо выполнить следующую команду:\n```sh\n$ ./bin/ffmpeg -i examples/in.wav -af \"[aid1] hsvden=mode=tsnrg [ao]\" examples/out.wav\n```\n\nгде `wiener` - один из видов алгоритмов шумоподавления;\n`examples/in.wav` - входной `wav`-файл;\n`examples/out.wav` - выходной `wav`-файл;\n\nПри использовании **HSV** в `FFmpeg` можно задавать следующие флаги:\n- `mode` (`m`) - режим работы шумоподавления:\n   - `specsub` - спектральное вычитание Берути-Шварца;\n   - `wiener` - винеровская фильтрация Скалара;\n   - `tsnr` - двухшаговая фильтрация Скалара;\n   - `tsnrg` - двухшаговая фильтрация Скалара с \"усилением\";\n   - `rtsnr` - двухщаговая фильтрация Шифенга;\n   - `rtsnrg` - двухшаговая фильтрация Шифенга с \"усилением\";\n\n- `frame` (`f`) - размер одного обрабатываемого фрейма в сэмплах. Рекомендуются значения `2.0 * sr / 100.0` или близкие к ним степени двойки;\n\n- `overlap` (`o`) - величина перекрытия фреймов в процентах. Рекумендуются значения 50-75%;\n\n- `dft` (`d`) - размер дискретного преобразования Фурье в сэмплах. Рекомендуется брать как удвоенный размер фрейма для увеличения частотного разрешения.;\n\n- `cap` (`c`) - вместимость кольцевого буфера в байтах. Должна быть кратна 2 и достаточно велика для упреждения задержек;\n\nФлаги задаются через `:`, например:\n```sh\n$ ./bin/ffmpeg -i examples/in.wav -af \"[aid1] hsvden=mode=tsnrg:o=50:cap=32768 [ao]\" examples/out.wav\n```\n\n## Встраивание в MPV\n\n`MPV` - это компактный свободный кроссплатформенный медиаплеер, основанный на `MPlayer/mplayer2`. Он крайне активно используется и развивается с 2012 года по сей день. Встраивание **HSV** в `MPV` является наглядной демонстрацией работы библиотеки шумоочистки в реальном времени, так как при воспроизведении аудио- или видеопотока **HSV** имеет доступ лишь к текущим фреймам звука и не должна вносить существенной задержки в воспроизведение.\n\nЧтобы собрать `MPV` с поддержкой **HSV**, необходимо выполнить следующие шаги:\n\n- скачать официальный набор скриптов сборки `MPV` и выполнить сборку чистого `MPV`. Сборка автоматические подтянет все зависимости:\n```sh\n$ git clone https://github.com/mpv-player/mpv-build.git\n$ cd mpv-build\n$ ./rebuild -j8\n```\n\n- далее нужно очистить оригинальный `MPV` от результатов прошлой сборки и удалить скачанный `FFmpeg`:\n```sh\n$ cd mpv-build\n$ ./clean\n$ rm -rf ffmpeg\n```\n\n- затем аналогично пункту про встраивание в `FFmpeg` нужно скачать архив с кодом `FFmpeg`, распаковать его и пропатчить, но не собирать (!!!). Далее пропатченный исходный код `FFmpeg` следует поместить в папку `mpv-build`:\n```sh\n$ mkdir -p ~/ffmpeg_sources\n$ cd ~/ffmpeg_sources\n$ wget -O ffmpeg-snapshot.tar.bz2 https://ffmpeg.org/releases/ffmpeg-snapshot.tar.bz2\n$ tar xjvf ffmpeg-snapshot.tar.bz2\n$ cp -r HSV/ffmpeg/* ~/ffmpeg_sources\n$ ./apply_patches.sh\ncp -r ~/ffmpeg_sources/ffmpeg ~/mpv-build\n```\n\n- после этого необходимо заменить файл `rebuild` в `mpv-build` на файл, лежащий в папке `HSV/mpv`. После этого выполнить пересборку `MPV`:\n```sh\n$ cp HSV/mpv/rebuild mpv-build/rebuild\n$ cd mpv-build\n$ ./rebuild -j8\n```\n\n- после этого в папке `~/mpv-build/mpv/build` должна появиться сборка `MPV` с поддержкой библиотеки `HSV`. Для запуска `MPV` с одним из фильтров `HSV` необходимо выполнить следующую команду:\n```sh\n$ ./mpv-build/mpv/build/mpv examples/in.wav -af lavfi=\"[hsvden=m=rtsnr]\"\n```\n\nгде `wiener` - один из видов алгоритмов шумоподавления;\n`examples/in.wav` - входной `wav`-файл;\n`examples/out.wav` - выходной `wav`-файл;\n\nВ целом использование **HSV** в `MPV` совпадает с использованием **HSV** в `FFmpeg`.\n\n## Документация\n\nВсе комментарии к библиотеке **HSV** совместимы с [Doxygen](https://www.doxygen.nl/). Чтобы сгенерировать и открыть документацию в формате [HTML](https://www.w3.org/TR/html52/) необходимо выполнить следующие шаги:\n\n```sh\n$ doxygen docs/doxygen.conf\n$ firefox doxygen/html/index.html\n```\n\n## Объективная оценка качества шумоочистки\n\nДля проведения тестов эффективности как **HSV**, так и других алгоритмов шумоочистки, в папке `scripts` имеются скрипты для вычисления [ОСШ](https://ru.wikipedia.org/wiki/%D0%9E%D1%82%D0%BD%D0%BE%D1%88%D0%B5%D0%BD%D0%B8%D0%B5_%D1%81%D0%B8%D0%B3%D0%BD%D0%B0%D0%BB/%D1%88%D1%83%D0%BC), сегментного ОСШ и [PESQ](https://www.itu.int/rec/T-REC-P.862).\n\nЧем выше значения `SNR` и `PESQ` по сравнению с зашумленным сигналом, тем выше качество шумоочистки. Замечу, что повышение одной метрики зачастую не гарантирует повышение другой.\n\n## Пример работы\n\nВ папке `data` можно найти примеры работы всех алгоритмов шумоочистки на мультишумовом примере. Также доступен архив с более чем 500 мегабайтами тестовых данных и сравнением разработанного алгоритма с `WebRTC` и `Speex` по [данной ссылке](https://yadi.sk/d/ttNJxNwO3E8zkg). Эффективность шумоочистки может быть оценена скриптами для вычисления `ОСШ`, сегментного `ОСШ` и `PESQ` из папки `scripts`.\n\n- Чистый сигнал: PESQ=4.5, SegSNR = 35;\n![clean](https://github.com/masyagin1998/HSV/blob/master/docs/pics/10/clean.png)\n\n- Шум: PESQ=0.0, SegSNR = -10;\n![noise](https://github.com/masyagin1998/HSV/blob/master/docs/pics/10/noise.png)\n\n- Зашумленный сигнал: PESQ=0.887, SegSNR = -0.542;\n![noised](https://github.com/masyagin1998/HSV/blob/master/docs/pics/10/noised.png)\n\n- Спектральное вычитание: PESQ=1.440, SegSNR = 3.841;\n![specsub](https://github.com/masyagin1998/HSV/blob/master/docs/pics/10/specsub.png)\n\n- Винеровская фильтрация Скалара: PESQ=1.807, SegSNR = 4.008;\n![wiener](https://github.com/masyagin1998/HSV/blob/master/docs/pics/10/wiener.png)\n\n- TSNR: PESQ=1.826, SegSNR = 4.414;\n![tsnr](https://github.com/masyagin1998/HSV/blob/master/docs/pics/10/tsnr.png)\n\n- RTSNR: PESQ=1.778, SegSNR = 4.549;\n![rtsnr](https://github.com/masyagin1998/HSV/blob/master/docs/pics/10/rtsnr.png)\n\n## Ссылки на основную использованную литературу\n\n- [Loizou P. C. Speech Enhancement. Theory and Practice. Second Edition // CRC Press, 2013 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/estimator/Loizou_P_C_Speech_Enhancement.pdf) - лучшая книга, вводящая в теорию шумоочистки речевых сигналов;\n- [Cohen I., Berdugo B. Noise Estimation by Minima Controlled Recursive Averaging for Robust Speech Enhancement // Lamar Signal Processing Ltd., 2002 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/estimator/Cohen_I_MCRA.pdf) - оригинальный алгоритм детектирования шума MCRA;\n- [Scalart P., Filho J. V. Speech enhancement based on a priori SNR estimator // Acoustics, Speech and Signal Processing, 1996 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/suppressor/Scalart_P_Wiener.pdf) - оригинальный алгоритм винеровской фильтрации, предложенный Скаларом;\n- [Scalart P., Plapous C. A two-step noise reduction technique // Acoustics, Speech and Signal Processing, 2004 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/suppressor/Scalart_P_TSNR.pdf) - улучшенный вариант алгоритма винеровской фильтрации, также известный как `TSNR`;\n- [Shifeng Ou, Chao G., Ying G. Improve a priori SNR estimator  for speech enhancement incorporating speech distortion component // Yantai Univercity, 2013 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/suppressor/Shifeng_Ou_RTSNR.pdf) - улучшенный вариант алгоритма винеровской фильтрации, также известный как `RTSNR`;\n- [Тропченко А. Ю., Тропченко А. А. Цифровая обработка сигналов // ИТМО, 2009 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/fft/%D0%A2%D1%80%D0%BE%D0%BF%D1%87%D0%B5%D0%BD%D0%BA%D0%BE_%D0%90_%D0%A6%D0%9E%D0%A1.pdf) - книга с хорошим описанием алгоритма БПФ Кули-Тьюки;\n- [Кренёв А. Н., Артёмова Т. К. Цифровой анализ сигналов // ЯГУ, 2003 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/fft/%D0%9A%D1%80%D0%B5%D0%BD%D1%91%D0%B2_%D0%90_%D0%A6%D0%A1%D0%90.pdf) - книга с хорошим описанием алгоритма БПФ Блюштейна;\n- [Fukane A. R., Shashikant L. S. Noise Estimation Algorithms for Speech Enhancement in highly non-stationary environments // 2011 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/comparison/estimators.pdf) - сравнительный анализ алгоритмов детектирвоания шума;\n- [Shrawankar U., Thakare V. M. Performance Analysis of Noise Filters and Speech Enhancement Techniques // 2012 г.](https://github.com/masyagin1998/HSV/blob/master/docs/articles/comparison/suppressors.pdf) - сравнительный анализ множества алгоритмов шумоочистки;\n\n## Благодарности\n\n- Игорю Эдуардовичу Вишнякову и Олегу Александровичу Одинцову - моим научными руководителям;\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasyagin1998%2Fhsv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmasyagin1998%2Fhsv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasyagin1998%2Fhsv/lists"}