{"id":36443151,"url":"https://github.com/alexeidt/aio","last_synced_at":"2026-01-11T22:00:59.789Z","repository":{"id":49753244,"uuid":"517895400","full_name":"AlexEidt/aio","owner":"AlexEidt","description":"Read, Write and Play Audio using FFmpeg, FFprobe and FFplay.","archived":false,"fork":false,"pushed_at":"2023-03-18T16:54:10.000Z","size":200,"stargazers_count":17,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-06-22T07:49:12.144Z","etag":null,"topics":["audio-io","audio-player","ffmpeg-wrapper"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/AlexEidt/aio","language":"Go","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/AlexEidt.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":"2022-07-26T03:09:40.000Z","updated_at":"2024-04-24T15:11:01.000Z","dependencies_parsed_at":"2024-06-20T05:48:13.715Z","dependency_job_id":"eabc0063-c16f-4d1b-a0f9-b8a60a32d89f","html_url":"https://github.com/AlexEidt/aio","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/AlexEidt/aio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexEidt%2Faio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexEidt%2Faio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexEidt%2Faio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexEidt%2Faio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexEidt","download_url":"https://codeload.github.com/AlexEidt/aio/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexEidt%2Faio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28324835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T18:42:50.174Z","status":"ssl_error","status_checked_at":"2026-01-11T18:39:13.842Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["audio-io","audio-player","ffmpeg-wrapper"],"created_at":"2026-01-11T22:00:58.813Z","updated_at":"2026-01-11T22:00:59.774Z","avatar_url":"https://github.com/AlexEidt.png","language":"Go","readme":"# `aio`\n\nA simple Audio I/O library written in Go. This library relies on [FFmpeg](https://www.ffmpeg.org/), [FFProbe](https://ffmpeg.org/ffprobe.html) and [FFPlay](https://ffmpeg.org/ffplay.html) which must be downloaded before usage and added to the system path.\n\nFor Video I/O using FFmpeg. see the [`Vidio`](https://github.com/AlexEidt/Vidio) project.\n\n## Installation\n\n```\ngo get github.com/AlexEidt/aio\n```\n\n## Buffers\n\n`aio` uses `byte` buffers to transport raw audio data. Audio data can take on many forms, including floating point, unsigned integer and signed integer. These types may be larger than a `byte` and would have to be split. Valid formats are `u8`, `s8`, `u16`, `s16`, `u24`, `s24`, `u32`, `s32`, `f32`, and `f64`. These represent `u` unsigned integers, `s` signed integers and `f` floating point numbers.\n\nAs an example, if there is stereo sound (two channels) encoded in the `s16` (signed 16 bit integers) format with a sampling rate of `44100 Hz`, one second of audio would be\n\n```\n44100 * 2 (channels) * 2 (bytes per sample) = 176400 bytes\n```\n\nContinuing on with this example, since this is stereo audio with 2 channels, one frame of audio is represented by 2 consecutive integers, one for each channel. Each integer is 16 bits, which means one frame of audio would be represented by 4 consecutive bytes.\n\n## `Options`\n\nThe `Options` struct is used to specify optional parameters for Audio I/O.\n\n```go\ntype Options struct {\n\tStream     int    // Audio Stream Index to use.\n\tSampleRate int    // Sample rate in Hz.\n\tChannels   int    // Number of channels.\n\tBitrate    int    // Bitrate in bits/s.\n\tFormat     string // Format of audio.\n\tCodec      string // Audio Codec.\n\tStreamFile string // File path for extra stream data.\n}\n```\n\nThe `Options.StreamFile` parameter is intended for users who wish to alter an audio stream from a video. Instead of having to process the audio and store in a file and then combine with the video later, the user can simply pass in the original video file path via the `Options.StreamFile` parameter. This will combine the audio with all other streams in the given video file (Video, Subtitle, Data, and Attachments Streams) and will cut all streams to be the same length. **Note that `aio` is not a audio/video editing library.**\n\nThis means that adding extra stream data from a file will only work if the `filename` being written to is a container format, i.e attempting to add video streams to a `wav` file will result in undefined behavior.\n\n## `Audio`\n\n`Audio` is used to read audio from files. It can also be used to gather audio metadata from a file. By default, the audio buffer has a length of\n\n```\nsample rate * channels * bytes per sample\n```\n\nwhich corresponds to 1 second of audio data.\n\nThe user may pass in `options` to set the desired sampling rate, format and channels of the audio. If `options` is `nil`, then the channels and sampling rate from the file will be used, with a default format of `s16`.\n\nThe `Read()` function fills the internal byte buffer with the next batch of audio samples. Once the entire file has been read, `Read()` will return `false` and close the `Audio` struct.\n\nNote that the `Samples()` function is only present for convenience. It casts the raw byte buffer into the given audio data type determined by the `Format()` such that the underlying data buffers are the same. The `s24` and `u24` formats are not supported by the `Samples()` function since there is no type equivalent. Calling the `Samples()` function on 24-bit audio will return the raw byte buffer.\n\nThe return value of the `Samples()` function will have to be cast into an array of the desired type (e.g. `audio.Samples().([]float32)`)\n\n```go\naio.NewAudio(filename string, options *aio.Options) (*aio.Audio, error)\naio.NewAudioStreams(filename string, options *aio.Options) ([]*aio.Audio, error)\n\nFileName() string\nSampleRate() int\nChannels() int\nBitrate() int\nBitsPerSample() int\nStream() int\nTotal() int\nDuration() float64\nFormat() string\nCodec() string\nHasStreams() bool\nBuffer() []byte\nMetaData() map[string]string\nSamples() interface{}\nSetBuffer(buffer []byte) error\n\nRead() bool\nClose()\n```\n\n## `AudioWriter`\n\n`AudioWriter` is used to write audio to files from a buffer of audio samples. It comes with an `Options` struct that can be used to specify certain metadata of the output audio file. If `options` is `nil`, the defaults used are a sampling rate of `44100 Hz`, with `2` channels in the `s16` format.\n\n```go\naio.NewAudioWriter(filename string, options *aio.Options) (*aio.AudioWriter, error)\n\nFileName() string\nStreamFile() string\nSampleRate() int\nChannels() int\nBitrate() int\nFormat() string\nCodec() string\n\nWrite(samples interface{}) error\nClose()\n```\n\n## `Microphone`\n\n`Microphone` is similar to the `Audio` struct, the only difference being that it reads audio from the microphone. The `stream` parameter is used to specify the microphone stream index, which will differ depending on the platform. For Windows (`dshow`) and MacOS (`avfoundation`), find the stream index by entering the following command\n\n```\nffmpeg -f [dshow | avfoundation] -list_devices true -i dummy\n```\n\nand selecting the desired stream. For linux, see [this page](https://trac.ffmpeg.org/wiki/Capture/PulseAudio) on the FFmpeg Wiki.\n\nAdditionally, an `options` parameter may be passed to specify the format, sampling rate and audio channels the microphone should record at. Any other options are ignored.\n\n```go\naio.NewMicrophone(stream int, options *aio.Options) (*aio.Microphone, error)\n\nName() string\nSampleRate() int\nChannels() int\nBitsPerSample() int\nFormat() string\nBuffer() []byte\nSamples() interface{}\nSetBuffer(buffer []byte) error\n\nRead() bool\nClose()\n```\n\n## `Player`\n\n`Player` is used to play audio from a buffer of audio samples.\n\n```go\naio.NewPlayer(channels, samplerate int, format string) (*aio.Player, error)\n\nSampleRate() int\nChannels() int\nFormat() string\nPlay(samples interface{}) error\nClose()\n```\n\n## Examples\n\nCopy `input.wav` to `output.mp3`.\n\n```go\naudio, _ := aio.NewAudio(\"input.wav\", nil)\n\noptions := aio.Options{\n\tSampleRate: audio.SampleRate(),\n\tChannels:   audio.Channels(),\n\tBitrate:    audio.Bitrate(),\n\tFormat:     audio.Format(),\n}\n\nwriter, _ := aio.NewAudioWriter(\"output.mp3\", \u0026options)\ndefer writer.Close()\n\nfor audio.Read() {\n\twriter.Write(audio.Buffer())\n}\n```\n\nCapture 10 seconds of audio from the microphone. Audio is recorded at 44100 Hz stereo and is in signed 16 bit format.\n\n```go\nmicOptions := aio.Options{Format: \"s16\", Channels: 2, SampleRate: 44100}\nmic, _ := aio.NewMicrophone(0, \u0026micOptions)\ndefer mic.Close()\n\nwriterOptions := aio.Options{\n\tSampleRate: mic.SampleRate(),\n\tChannels:   mic.Channels(),\n\tFormat:     mic.Format(),\n}\n\nwriter, _ := aio.NewAudioWriter(\"output.wav\", \u0026writerOptions)\ndefer writer.Close()\n\nseconds := 0\nfor mic.Read() \u0026\u0026 seconds \u003c 10 {\n\twriter.Write(mic.Buffer())\n\tseconds++\n}\n```\n\nPlay all audio tracks from `input.mp4` sequentially.\n\n```go\nstreams, _ := aio.NewAudioStreams(\"input.mp4\", nil)\n\nfor _, stream := range streams {\n\tplayer, _ := aio.NewPlayer(stream.Channels(), stream.SampleRate(), stream.Format())\n\tfor stream.Read() {\n\t\tplayer.Play(stream.Buffer())\n\t}\n\tplayer.Close()\n}\n```\n\nPlay `input.mp4`.\n\n```go\naudio, _ := aio.NewAudio(\"input.mp4\", nil)\nplayer, _ := aio.NewPlayer(audio.Channels(), audio.SampleRate(), audio.Format())\ndefer player.Close()\n\nfor audio.Read() {\n\tplayer.Play(audio.Buffer())\n}\n```\n\nRead `input.wav` and process the audio samples.\n\n```go\naudio, _ := aio.NewAudio(\"input.wav\", nil)\n\nfor audio.Read() {\n\tsamples := audio.Samples().([]int16)\n\tfor i := range samples {\n\t\t// audio processing...\n\t}\n}\n```\n\nCombine `sound.wav` and `movie.mov` into `output.mp4`.\n\n```go\naudio, _ := aio.NewAudio(\"sound.wav\", nil)\n\noptions := aio.Options{\n\tSampleRate: audio.SampleRate(),\n\tChannels:   audio.Channels(),\n\tBitrate:    audio.Bitrate(),\n\tFormat:     audio.Format(),\n\tCodec:      \"aac\",\n\tStreamFile: \"movie.mov\",\n}\n\nwriter, _ := aio.NewAudioWriter(\"output.mp4\", \u0026options)\ndefer writer.Close()\n\nfor audio.Read() {\n\twriter.Write(audio.Buffer())\n}\n```\n\nPlay Microphone audio. Use default microphone settings for recording.\n\n```go\nmic, _ := aio.NewMicrophone(0, nil)\ndefer mic.Close()\n\nplayer, _ := aio.NewPlayer(mic.Channels(), mic.SampleRate(), mic.Format())\ndefer player.Close()\n\nfor mic.Read() {\n\tplayer.Play(mic.Buffer())\n}\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexeidt%2Faio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexeidt%2Faio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexeidt%2Faio/lists"}