{"id":20332818,"url":"https://github.com/xasworks/esp-libopus","last_synced_at":"2025-04-11T21:33:06.659Z","repository":{"id":176059638,"uuid":"311151022","full_name":"XasWorks/esp-libopus","owner":"XasWorks","description":"ESP32 component that straightup ports LibOpus to the Build System","archived":false,"fork":false,"pushed_at":"2020-11-17T21:31:24.000Z","size":680,"stargazers_count":69,"open_issues_count":3,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-25T17:46:43.127Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XasWorks.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-08T20:43:20.000Z","updated_at":"2025-03-03T10:09:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"dedeb69f-2ee5-4787-a56e-7ae61231c85d","html_url":"https://github.com/XasWorks/esp-libopus","commit_stats":null,"previous_names":["xasworks/esp-libopus"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XasWorks%2Fesp-libopus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XasWorks%2Fesp-libopus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XasWorks%2Fesp-libopus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XasWorks%2Fesp-libopus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XasWorks","download_url":"https://codeload.github.com/XasWorks/esp-libopus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248483118,"owners_count":21111427,"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","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":[],"created_at":"2024-11-14T20:28:23.151Z","updated_at":"2025-04-11T21:33:06.650Z","avatar_url":"https://github.com/XasWorks.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# esp-libopus\n\n*Original README content further below*\n\nThis repository is a port of the original Opus code for the ESP32. It\nprovides a component.mk makefile with the necessary configuration to compile and\nuse the Opus audio codec on the ESP32. It also removes the original build system\nof Opus to not clutter the filetree and confuse the ESP32 build system.\n\n### Usage\nThis repository can be added as submodule to any valid ESP32 component directory.\nThe easiest way to do this is to create a `component/` directory in the root\nof an ESP project, using `git submodule add` to clone this repo into there,\nand to ensure that this new component is recognized via `make list-components`.\n\n*Note:* Currently the component.mk file might only work for the older build system\nof the ESP-IDF, however creating a config file for the newer build system should\nbe fairly trivial.\n\nAfter adding this component to the build configuration, the \"opus.h\" file\ncan be included. All *fixed point* Opus decoder and encoder methods are available,\nconsult the Opus documentation for examples.\n\n#### Important considerations\nOpus is a fairly heavy codec, and it might not always work smoothly on the ESP32.\nThe following things have to be taken into account:\n\n- Encoding and Decoding heavily utilize Stack via `alloca`. It is recommended\nto have at least 30kB of Stack reserved for the FreeRTOS thread that is running\nthe Opus encoding/decoding (the stack is freed after the Opus call, so a single\nthread can encode and decode).\n- Decoding data on the ESP32 is fairly lightweight, and will consume about 30% of\nthe CPU time at 240MHz on a single core, even at 48kHz samplerate. This makes\nit fairly usable.\n- *Encoding* however is much more intensive. 16kHz samplerate\nat encoding complexity 1 will use 70% CPU. 24kHz samplerate at anything above\ncomplexity 4 will *not be able to run at realtime*. 48kHz can only run at\nrealtime with complexity 1, and even then it uses 85% CPU. It still sounds\nunderstandable at 16kHz if you just need basic VoIP or voice recognition though,\nbut don't expect to encode high quality music.\n\nAdditionally, the WiFi of the ESP32 is very capable of high throughputs, so\nthe Samplerate is rarely an issue. What I have found to be problematic is the\nunstable latency of the network. The ESP will receive in \"chunks\" of a few\npackets, then pause for about 300ms, give or take.\nIf you want to use Opus to stream Audio, make sure to have a bigger buffer of\none or two seconds worth of audio on the receiving end, so that these lagspikes\ncan be smoothed out. Once you do that though it's quite easy to have a very\nnice sounding audio stream.\n\n**Todo:** Add a class that provides an easy to use ESP32 MQTT Audio stream.\nIt'll need to handle decoding the data, providing it to the XasWorks audio\ncore (which will need a slight rework, oh well), and keeping the buffer in synch\nby varying playback speed a bit (clock drift and stuff).\n\nIf I do get around to doing this, it'll be in my [XasWorks](https://github.com/XasWorks/XasCode)\nrepository, so check it out.\n\n# Opus audio codec\n*Original readme:*\n\nOpus is a codec for interactive speech and audio transmission over the Internet.\n\n  Opus can handle a wide range of interactive audio applications, including\nVoice over IP, videoconferencing, in-game  chat, and even remote live music\nperformances. It can scale from low bit-rate narrowband speech to very high\nquality stereo music.\n\n  Opus, when coupled with an appropriate container format, is also suitable\nfor non-realtime  stored-file applications such as music distribution, game\nsoundtracks, portable music players, jukeboxes, and other applications that\nhave historically used high latency formats such as MP3, AAC, or Vorbis.\n\n                    Opus is specified by IETF RFC 6716:\n                    https://tools.ietf.org/html/rfc6716\n\n  The Opus format and this implementation of it are subject to the royalty-\nfree patent and copyright licenses specified in the file COPYING.\n\nThis package implements a shared library for encoding and decoding raw Opus\nbitstreams. Raw Opus bitstreams should be used over RTP according to\n https://tools.ietf.org/html/rfc7587\n\nThe package also includes a number of test  tools used for testing the\ncorrect operation of the library. The bitstreams read/written by these\ntools should not be used for Opus file distribution: They include\nadditional debugging data and cannot support seeking.\n\nOpus stored in files should use the Ogg encapsulation for Opus which is\ndescribed at:\n https://tools.ietf.org/html/rfc7845\n\nAn opus-tools package is available which provides encoding and decoding of\nOgg encapsulated Opus files and includes a number of useful features.\n\nOpus-tools can be found at:\n https://git.xiph.org/?p=opus-tools.git\nor on the main Opus website:\n https://opus-codec.org/\n\n## Testing\n**Todo:** Add testing according to the Opus test system. This is currently\nnot implemented on the ESP32 variant of libopus\n\n## Portability notes\n*Note:* Fixed point is used for the ESP32. Floating point is disabled\nvia a compiler define. The ESP32's FPU is way too slow for this.\n\nThis implementation uses floating-point by default but can be compiled to\nuse only fixed-point arithmetic by setting --enable-fixed-point (if using\nautoconf) or by defining the FIXED_POINT macro (if building manually).\nThe fixed point implementation has somewhat lower audio quality and is\nslower on platforms with fast FPUs, it is normally only used in embedded\nenvironments.\n\nThe implementation can be compiled with either a C89 or a C99 compiler.\nWhile it does not rely on any _undefined behavior_ as defined by C89 or\nC99, it relies on common _implementation-defined behavior_ for two's\ncomplement architectures:\n\no Right shifts of negative values are consistent with two's\n  complement arithmetic, so that a\u003e\u003eb is equivalent to\n  floor(a/(2^b)),\n\no For conversion to a signed integer of N bits, the value is reduced\n  modulo 2^N to be within range of the type,\n\no The result of integer division of a negative value is truncated\n  towards zero, and\n\no The compiler provides a 64-bit integer type (a C99 requirement\n  which is supported by most C89 compilers).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxasworks%2Fesp-libopus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxasworks%2Fesp-libopus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxasworks%2Fesp-libopus/lists"}