jhasse / ears

Easy Api in Rust to play Sounds

ears

ears is a simple library to play sounds and music in Rust.

• Provides an access to the OpenAL spatialization functionality in a simple way.
• Accepts a lot of audio formats, thanks to libsndfile.

Building

You need to install OpenAL and libsndfile on your system:

Linux

Fedora:

sudo dnf install openal-soft-devel libsndfile-devel

Debian or Ubuntu:

sudo apt install libopenal-dev libsndfile1-dev

Mac

brew install openal-soft libsndfile

Windows

Install MSYS2 according to the instructions. Be sure to use the default installation folder (i.e. C:\msys32 or C:\msys64), otherwise compiling won't work. Then, run the following in the MSYS2 shell:

pacman -S mingw-w64-x86_64-libsndfile mingw-w64-x86_64-openal

Examples

cargo run --example basic
cargo run --example many_sounds
cargo run --example music
cargo run --example record
cargo run --example simple_player

Functionality

ears provides two ways to play audio files:

• The Sound class, which represents light sounds who can share a buffer of samples with another Sound.
• The Music class, which represents bigger sound and can't share sample buffers.

ears's Issues

Build failed on latest nightly

The following error occurs during a build for ears 0.4.0 on rust 1.17.0-nightly (0aeb9c129 2017-03-15)

error[E0282]: type annotations needed
   --> /home/user/.cargo/git/checkouts/ears-61786ad5106195e7/b48a9e1/src/internal.rs:129:25
    |
129 |                         Err("Error: you must request the input context, \
    |                         ^^^ cannot infer type for `T`

error: aborting due to previous error

error: Could not compile `ears`.

To learn more, run the command again with --verbose.

AppVeyor fails

Seems that openal32 has been renamed in MSYS2?

Error when building for ARMv6

Hi!

I have a project using ears. I'm trying to compile it to ARMv6, but I'm getting the following error:

$ xargo build --target=arm-unknown-linux-gnueabihf --release
   Compiling ears v0.5.1
   Compiling wayland-client v0.12.5
   Compiling jpeg-decoder v0.1.15
   Compiling pistoncore-event_loop v0.37.0
   Compiling piston v0.37.0
error: linking with `arm-linux-gnueabihf-gcc` failed: exit code: 1
  |
  = note: "arm-linux-gnueabihf-gcc" "-Wl,--as-needed" "-Wl,-z,noexecstack" "-L" "/home/agustin/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/arm-unknown-linux-gnueabihf/lib" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears0-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears1-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears10-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears11-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears12-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears13-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears14-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears15-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears2-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears3-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears4-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears5-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears6-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears7-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears8-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.ears9-6b2dd9bcd030ef70c97df7db65d010ca.rs.rcgu.o" "-o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/libears-e272dc79f79667e4.so" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.crate.metadata.rcgu.o" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps/ears-e272dc79f79667e4.crate.allocator.rcgu.o" "-Wl,-z,relro,-z,now" "-Wl,-O1" "-nodefaultlibs" "-L" "/home/agustin/projects/emulators/target/arm-unknown-linux-gnueabihf/release/deps" "-L" "/home/agustin/projects/emulators/target/release/deps" "-L" "/usr/local/opt/openal-soft/lib" "-L" "/usr/local/lib" "-L" "/home/agustin/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/arm-unknown-linux-gnueabihf/lib" "-l" "openal" "-l" "sndfile" "-Wl,-Bstatic" "-Wl,--whole-archive" "/tmp/rustc.Ed5wsrhR7jAU/liblazy_static-f4ce19faecf5cd71.rlib" "-Wl,--no-whole-archive" "-Wl,--whole-archive" "/tmp/rustc.Ed5wsrhR7jAU/liblibc-11194f979f69d9b5.rlib" "-Wl,--no-whole-archive" "-Wl,--start-group" "-L" "/home/agustin/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/arm-unknown-linux-gnueabihf/lib" "-Wl,-Bdynamic" "-l" "std-9a440ef90899818f" "-Wl,--end-group" "-Wl,-Bstatic" "/tmp/rustc.Ed5wsrhR7jAU/libcompiler_builtins-874d313336916306.rlib" "-Wl,-Bdynamic" "-l" "util" "-l" "util" "-l" "dl" "-l" "rt" "-l" "pthread" "-l" "pthread" "-l" "gcc_s" "-l" "c" "-l" "m" "-l" "rt" "-l" "pthread" "-l" "util" "-l" "util" "-shared"
  = note: /usr/local/lib/libopenal.so: file not recognized: File format not recognized
          collect2: error: ld returned 1 exit status
          

error: aborting due to previous error

error: Could not compile `ears`.
warning: build failed, waiting for other jobs to finish...
error: build failed

Some information:

$ rustup show
Default host: x86_64-unknown-linux-gnu

installed toolchains
--------------------

stable-x86_64-unknown-linux-gnu
nightly-x86_64-unknown-linux-gnu
1.23.0-x86_64-unknown-linux-gnu

installed targets for active toolchain
--------------------------------------

arm-unknown-linux-gnueabihf
x86_64-unknown-linux-gnu

active toolchain
----------------

stable-x86_64-unknown-linux-gnu (default)
rustc 1.28.0 (9634041f0 2018-07-30)

$ arm-linux-gnueabihf-gcc --version
arm-linux-gnueabihf-gcc (GCC) 8.1.0
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

$ file /usr/local/lib/libopenal.so
/usr/local/lib/libopenal.so: symbolic link to /usr/lib/libopenal.so
$ file /usr/lib/libopenal.so
/usr/lib/libopenal.so: symbolic link to libopenal.so.1
$ file /usr/lib/libopenal.so.1
/usr/lib/libopenal.so.1: symbolic link to libopenal.so.1.18.2
$ file /usr/lib/libopenal.so.1.18.2
/usr/lib/libopenal.so.1.18.2: ELF 64-bit LSB pie executable x86-64, version 1 (SYSV), dynamically linked, BuildID[sha1]=b64a34de15967f08feb2e4ea4e2a1bb9258b2500, stripped

Any idea what am I doing wrong? Thanks!

AuxiliaryEffect function is not exported

It seem that AuxiliaryEffect function is not exported by OpenAL?

In the example code of OpenAL,we can see:

		alGenAuxiliaryEffectSlots = (LPALGENAUXILIARYEFFECTSLOTS)alGetProcAddress("alGenAuxiliaryEffectSlots");
		alDeleteAuxiliaryEffectSlots = (LPALDELETEAUXILIARYEFFECTSLOTS)alGetProcAddress("alDeleteAuxiliaryEffectSlots");
		alIsAuxiliaryEffectSlot = (LPALISAUXILIARYEFFECTSLOT)alGetProcAddress("alIsAuxiliaryEffectSlot");
		alAuxiliaryEffectSloti = (LPALAUXILIARYEFFECTSLOTI)alGetProcAddress("alAuxiliaryEffectSloti");
		alAuxiliaryEffectSlotiv = (LPALAUXILIARYEFFECTSLOTIV)alGetProcAddress("alAuxiliaryEffectSlotiv");
		alAuxiliaryEffectSlotf = (LPALAUXILIARYEFFECTSLOTF)alGetProcAddress("alAuxiliaryEffectSlotf");
		alAuxiliaryEffectSlotfv = (LPALAUXILIARYEFFECTSLOTFV)alGetProcAddress("alAuxiliaryEffectSlotfv");
		alGetAuxiliaryEffectSloti = (LPALGETAUXILIARYEFFECTSLOTI)alGetProcAddress("alGetAuxiliaryEffectSloti");
		alGetAuxiliaryEffectSlotiv = (LPALGETAUXILIARYEFFECTSLOTIV)alGetProcAddress("alGetAuxiliaryEffectSlotiv");
		alGetAuxiliaryEffectSlotf = (LPALGETAUXILIARYEFFECTSLOTF)alGetProcAddress("alGetAuxiliaryEffectSlotf");
		alGetAuxiliaryEffectSlotfv = (LPALGETAUXILIARYEFFECTSLOTFV)alGetProcAddress("alGetAuxiliaryEffectSlotfv");

So,these functions are dynamic called?

Allow creating Sound with a raw SoundData reference

Currently, as far as I understand, the only two ways of creating a Sound are:

1. create a new Sound along with a new SoundData;
2. create a new Sound from an existing SoundData wrapped in a Rc<RefCell<>>.

Is there a reason why you cannot create a Sound from a simple &SoundData, rather than a ref-counted pointer?
My use case is the following: I want to create a cache that only creates one SoundData per audio file, and share the same data among several Sounds. This is already possible of course, but since I'm using handles to access the cache, I have no benefit from using Rc and RefCell. From what I see in the code (https://github.com/jhasse/ears/blob/master/src/sound.rs#L131-L132) the new_with_data function does not need to clone the Rc either, so it looks like a method accepting a raw ref would not be hard to add.

If that's the case and you agree with it, I may try implementing it myself and open a PR :)

Stereo music sources not running in direct channel mode

It seems like openal-soft 1.17 added a new algorithm to "spread" stereo sources across multiple channels, which is colouring the sound even with only 2 channels (headphones). This doesn't sound great when you are attempting to play music produced and mixed for stereo.

One option is to disable HRTF all together, but that's not ideal because HRTF is actually great for everything else! Another is to configure specific sources to run in direct channel mode.

Considering that ears seems intended to be an easy way to get sensible behaviour out of OpenAL, I think most people would expect all music sources to run in direct channel mode.

Another alternative would be to add it as configurable option for music sources:

music.set_direct_channel(true);

But I'm not sure... Do you have any opinions on the best way to provide this feature?

I've been using this branch to fix the problem for myself, but it's likely something others would want too:
master...nickbrowne:prefer-direct-channel-music

If you're happy with my solution I'll gladly pull request it.

More info on direct channels here:
https://github.com/openalext/openalext/blob/master/AL_SOFT_direct_channels.txt

Allow seeking within audio

Something like a AudioControllable.seek would be amazing. Any change to get it implemented? It'd allow making applications that can move back and forth in audio, like a music player. Cheers!

Static link for compiling a Rust Binary

I've been trying to compile a rust binary and this is the error that I'm facing after I try to run it in a computer where OpenAL isn't already installed

dyld: Library not loaded: /usr/local/opt/openal-soft/lib/libopenal.1.dylib
  Referenced from: /Users/xxxxxx/Downloads/rustyvibes
  Reason: image not found

Would there be any way to static link the libraries for this crate?

Stuttering sound when using set_looping(true)

Hello.

I'm having trouble with the set_looping function from Music. Having the following snippet:

extern crate ears;

use ears::{Music, AudioController};

fn main() {
    let mut music = Music::new("res/music.ogg").unwrap();
    // This start the stutter:
    music.set_looping(true);
    music.play();
    while music.is_playing() {}
}

When run, it starts stuttering the first milliseconds of the sound forever. Not using set_looping makes the sound play properly as expected (only once). This didn't happened with the provided explosion.ogg file so I pressume the problem arises when dealing with long (> 2min) files.

I'm using:

• OSX 10.9.5
• Homebrew:
  • openal-soft 1.17.0
  • libsndfile: 1.0.26
• Rustc: 1.6.0

Better error handling

Right now, a lot of errors are returned using Option. I think it's more idiomatic and user friendly if errors are returned using Result, because then consumers of this library can use the error information to do their own error reporting, or handle an error gracefully. Currently the code handling errors just does hardcoded println!s, which is only unwanted output IMO, and causes information loss. It should be pretty simple to change uses of Option<T> to Result<T, &str> or something similar, and I'm willing to make a pull request for it.

How does I run ears with windows?

I want to run an ears-application on windows, but I can't compile.

There is Always this error:

error: linking with link.exefailed: exit code: 1181 | = note: "C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\VC\\bin\\amd64\\link.exe" "/LIBPATH:C:\\Program Files (x86)\\Microsoft Visual Studio 14.0\\VC\\lib\\amd64" "/LIBPATH:C:\\Program Files (x86)\\Windows Kits\\10\\lib\\10.0.10240.0\\ucrt\\x64" "/LIBPATH:C:\\Program Files (x86)\\Windows Kits\\8.1\\lib\\winv6.3\\um\\x64" "/NOLOGO" "/NXCOMPAT" "/LIBPATH:C:\\Users\\Andi\\.rustup\\toolchains\\stable-x86_64-pc-windows-msvc\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib" "C:\\Users\\Andi\\Desktop\\Git\\some_project\\target\\debug\\deps\\ears-f03cfcbcddf99b6f.0.o" "/OUT:C:\\Users\\Andi\\Desktop\\Git\\some_project\\target\\debug\\deps\\ears-f03cfcbcddf99b6f.dll" "/DEF:C:\\Users\\Andi\\AppData\\Local\\Temp\\rustc.EyrY6AH6bLTf\\lib.def" "C:\\Users\\Andi\\Desktop\\Git\\some_project\\target\\debug\\deps\\ears-f03cfcbcddf99b6f.metadata.o" "/OPT:REF,NOICF" "/DEBUG" "/LIBPATH:C:\\Users\\Andi\\Desktop\\Git\\some_project\\target\\debug\\deps" "/LIBPATH:C:\\Users\\Andi\\.rustup\\toolchains\\stable-x86_64-pc-windows-msvc\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib" "openal.lib" "sndfile.lib" "C:\\Users\\Andi\\AppData\\Local\\Temp\\rustc.EyrY6AH6bLTf\\liblibc-83c2bd88b43ecde3.rlib" "C:\\Users\\Andi\\AppData\\Local\\Temp\\rustc.EyrY6AH6bLTf\\liblazy_static-13daae1d9a07c252.rlib" "/LIBPATH:C:\\Users\\Andi\\.rustup\\toolchains\\stable-x86_64-pc-windows-msvc\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib" "std-259356a62c16e209.dll.lib" "C:\\Users\\Andi\\AppData\\Local\\Temp\\rustc.EyrY6AH6bLTf\\libcompiler_builtins-0c9c28ea236973f1.rlib" "advapi32.lib" "ws2_32.lib" "userenv.lib" "shell32.lib" "msvcrt.lib" "/DLL" "/IMPLIB:C:\\Users\\Andi\\Desktop\\Git\\some_project\\target\\debug\\deps\\ears-f03cfcbcddf99b6f.dll.lib" = note: Non-UTF-8 output: LINK : fatal error LNK1181: Eingabedatei \"openal.lib\" kann nicht ge\xf6ffnet werden.\r\n

I installedOpenAl and libsndfile for windows.
Moving the lib-files to the Visual-Studio-Folder gives a new error:

error: process didn't exit successfully: target\debug\chicken_fight_3000_ultimate_tournament.exe(exit code: 3221225781) C:/Users/Andi/.cargo/bin/cargo.exe: error while loading shared libraries: ?: cannot open shared object file: No such file or directory

Any way to play using include_bytes()?

It would be great if you could play music by a byte array, for example with include_bytes(). Cheers!

Implement std::marker::Send for ears::SoundData

Dear @jhasse can you make SoundData sendable between threads. Right now it's possible to move music into thread, but not a sound:
the trait boundstd::rc::Rcstd::cell::RefCellaudio::music::ears::SoundData: std::marker::Sendis not satisfied [E0277]

Find current cursor position within audio

Something like get_cursor (and get_length to know the max cursor pos) or such would be great.

Thread Safety

It looks like this doesn't (always) work in a multi threaded environment:

extern crate ears;
use ears::{Sound, AudioController};
use std::thread;

fn main() {
    let mut handles = Vec::new();
    for _ in 0..10 {
        let handle = thread::spawn(move || {
            let mut snd = Sound::new("path_to_audio.wav").unwrap();
            snd.play();
            while snd.is_playing() {}
        });
        handles.push(handle);
    }

    for h in handles {
        match h.join() {
            Ok(_)  => println!("Thread exited successfully"),
            Err(_) => println!("Thread died"),
        };
    }
}

I'm guessing its something to do with the underlying openal stuff, so it probably isn't easy to fix and may be outside of the scope of this library. But, if it wasn't too bad to fix, it sure would be nice. If you had any ideas about where to start looking to track this down, maybe I could look at stuff and see what could be done to fix it.

Panic: Illegal AL call

Getting a panic "Illegal AL call":

OpenAL error : Illegal AL call.
thread '<main>' panicked at 'called `Option::unwrap()` on a `None` value', ../src/libcore/option.rs:367

I'm doing something similar to this:

fn main() {
    run();
    run();
}

fn run() {
    let mut music = Music::new("./src/assets/music/tune.ogg").unwrap();
    music.set_looping(true);
    music.play();

    for e in window {
        // break after a while
    }
}

When run is called the second time it panics.