andelf / rust-sdl2_mixer Goto Github PK

View Code? Open in Web Editor NEW

13.0 4.0 17.0 158 KB

Rust bindings for sdl2_mixer

License: Apache License 2.0

Rust 100.00%

rust-sdl2_mixer's Introduction

As of rust-sdl2v0.27 this crate is deprecated and its functionality has been moved as a feature in rust-sdl2

Rust-SDL2_mixer

Rust bindings for SDL2_mixer.

Overview

Rust-SDL2_mixer is a library for talking to the new SDL2_mixer library from Rust.

Rust-SDL2_mixer uses the MIT licence.

Requirements

Rust-SDL2
SDL2_mixer development libraries
Latest stable Rust master

OSX

brew install sdl2_mixer --with-flac --with-fluid-synth --with-libmikmod --with-libmodplug --with-libvorbis --with-smpeg2

Windows

Download mingw development libraries from https://www.libsdl.org/projects/SDL_mixer/ (SDL2_mixer-devel-2.0.x-mingw.tar.gz)
Unpack to a folder of your choosing (You can delete it afterwards).
Copy all lib files from

SDL2_mixer-2.0.x\x86_64-w64-mingw32\lib\

to (for Rust 1.6 and above)

C:\Program Files\Rust\lib\rustlib\x86_64-pc-windows-gnu\lib

or to (for Rust versions 1.5 and below)

C:\Program Files\Rust\bin\rustlib\x86_64-pc-windows-gnu\lib

or to your library folder of choice, and ensure you have a system environment variable of

LIBRARY_PATH = C:\your\rust\library\folder

For Multirust Users, this folder will be in

C:\Users{Your Username}\AppData\Local.multirust\toolchains{current toolchain}\lib\rustlib\x86_64-pc-windows-gnu\lib
Copy SDL2_mixer.dll and smpeg2.dll from

SDL2_mixer-2.0.x\x86_64-w64-mingw32\bin\

into your cargo project, right next to your Cargo.toml.

Installation

Place the following into your project's Cargo.toml file:

[dependencies]
sdl2_mixer = "0.24.0"

Or, to depend on the newest rust-sdl2_mixer, reference the repository:

[dependencies.sdl2_mixer]
git = "https://github.com/andelf/rust-sdl2_mixer"

You can also just clone and build the library yourself:

git clone https://github.com/andelf/rust-sdl2_mixer
cd rust-sdl2_mixer
cargo build
# TODO: OR if you are using the mac framework version
rustc --cfg mac_framework src/sdl2_mixer/lib.rs

If you're not using Cargo, you can compile the library manually:

git clone https://github.com/andelf/rust-sdl2_mixer
cd rust-sdl2_mixer
rustc src/sdl2_mixer/lib.rs

Demo

A simple demo that plays out a portion of a given music file is included:

cargo run --example demo path/to/music.(mp3|flac|ogg|wav)

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

rust-sdl2_mixer's People

Contributors

Stargazers

Watchers

Forkers

devlato coeuvre lifthrasiir bvssvni steveklabnik akesling murilocadanus xilec caryhaynie tedsta crumblingstatue leod xaviershay markddr icefoxen cobrand mathstuf

rust-sdl2_mixer's Issues

Audio Callback method

Hey!

I'm after a method like this
https://github.com/PistonDevelopers/piston-workspace/issues/81

Does rust-sdl2_mixer support a "consistent" audio callback like this? If so, how do I access it? If not, where should I start looking to make one?

Cheers

how should i play sounds in the background?

i have a sound playing, but only if i use an sdl timer to block. do i have to manage a thread for each sound?

Build with environment variable 'SDL_MODE'

The Makefile of rust-sdl2 checks the ENV SDL_MODE to configure compile flags on OS X:

ifeq ($(UNAME),Darwin)
  # If the user wasn't explicit, see if SDL2 library exists
  ifeq ("$(strip $(SDL_MODE))","")
    SDL_CHECK=$(shell pkg-config --exists sdl2)
    ifeq ($(SDL_CHECK),0)
      SDL_MODE = dylib
    else
      SDL_MODE = framework
    endif
  endif

  ifeq ($(SDL_MODE),framework)
    RUSTFLAGS+=--cfg mac_framework
  else
    RUSTFLAGS+=--cfg mac_dylib
  endif
endif

However, the Makefile of rust-sdl2_mixer only build it with configuration --cfg mac_framework:

  COMPILER_FLAGS = -O --cfg mac_framework

I think it should be coincident between rust-sdl2 and rust-sdl2_mixer.

We can simply copy the script from rust-sdl2.

Actually publish a v0.25 crate please?

See PR #65 for why. :/

Relicense under dual MIT/Apache-2.0

This issue was automatically generated. Feel free to close without ceremony if
you do not agree with re-licensing or if it is not possible for other reasons.
Respond to @cmr with any questions or concerns, or pop over to
#rust-offtopic on IRC to discuss.

You're receiving this because someone (perhaps the project maintainer)
published a crates.io package with the license as "MIT" xor "Apache-2.0" and
the repository field pointing here.

TL;DR the Rust ecosystem is largely Apache-2.0. Being available under that
license is good for interoperation. The MIT license as an add-on can be nice
for GPLv2 projects to use your code.

Why?

The MIT license requires reproducing countless copies of the same copyright
header with different names in the copyright field, for every MIT library in
use. The Apache license does not have this drawback. However, this is not the
primary motivation for me creating these issues. The Apache license also has
protections from patent trolls and an explicit contribution licensing clause.
However, the Apache license is incompatible with GPLv2. This is why Rust is
dual-licensed as MIT/Apache (the "primary" license being Apache, MIT only for
GPLv2 compat), and doing so would be wise for this project. This also makes
this crate suitable for inclusion and unrestricted sharing in the Rust
standard distribution and other projects using dual MIT/Apache, such as my
personal ulterior motive, the Robigalia project.

Some ask, "Does this really apply to binary redistributions? Does MIT really
require reproducing the whole thing?" I'm not a lawyer, and I can't give legal
advice, but some Google Android apps include open source attributions using
this interpretation. Others also agree with
it.
But, again, the copyright notice redistribution is not the primary motivation
for the dual-licensing. It's stronger protections to licensees and better
interoperation with the wider Rust ecosystem.

How?

To do this, get explicit approval from each contributor of copyrightable work
(as not all contributions qualify for copyright) and then add the following to
your README:

## License

Licensed under either of
 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.

and in your license headers, use the following boilerplate (based on that used in Rust):

// Copyright (c) 2016 rust-sdl2_mixer developers
//
// Licensed under the Apache License, Version 2.0
// <LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0> or the MIT
// license <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. All files in the project carrying such notice may not be copied,
// modified, or distributed except according to those terms.

Be sure to add the relevant LICENSE-{MIT,APACHE} files. You can copy these
from the Rust repo for a plain-text
version.

And don't forget to update the license metadata in your Cargo.toml to:

license = "MIT/Apache-2.0"

I'll be going through projects which agree to be relicensed and have approval
by the necessary contributors and doing this changes, so feel free to leave
the heavy lifting to me!

Contributor checkoff

To agree to relicensing, comment with :

I license past and future contributions under the dual MIT/Apache-2.0 license, allowing licensees to chose either at their option

Or, if you're a contributor, you can check the box in this repo next to your
name. My scripts will pick this exact phrase up and check your checkbox, but
I'll come through and manually review this issue later as well.

Exposing Mix_LoadMUS_RW() would be nice

Even though the SDL2_mixer docs don't talk about it...

Update rust-sdl2_mixer to depend on sdl2-sys for low level SDL2 types, and move ffi.rs into sdl2_mixer-sys to conform to established cargo conventions

rust-sdl2 no longer directly exports the unsafe ("ll") sdl2 declarations, as these are now provided by the sdl2-sys library. Moreover, rust-sdl2_mixer needs to be updated to follow suit, as this API separation is part of established cargo conventions.

Add Windows install instructions for sdl2_mixer to README

As someone new to the sdl2 environment, it would be really helpful to have links and install instructions for SDL_mixer for Windows, similar to how rust-sdl2 provides one.

From what I could tell (would like someone more knowledgeable than I to review) you need to:

Download SDL2_mixer-devel-2.X.X-mingw.tar.gz from https://www.libsdl.org/projects/SDL_mixer/
Extract x86_64-w64-mingw32\lib\*
Ensure the extracted files are in in your LIBRARY_PATH
Copy SDL2_mixer.dll and smpeg2.dll next to Cargo.toml

Cannot run demo on OSX using Homebrew

When I try to play a simple WAV file on OSX using the demo example I receive the following output:

/Users/hagenjt1/.cargo/bin/cargo run --example demo piano.wav
   Compiling sdl2_mixer v0.24.0 (file:///Users/hagenjt1/GitHub/rust-sdl2_mixer)
    Finished debug [unoptimized + debuginfo] target(s) in 0.44 secs
     Running `target/debug/examples/demo piano.wav`
linked version: 2.0.1
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: "Mixer not built with Ogg Vorbis support"', ../src/libcore/result.rs:788
note: Run with `RUST_BACKTRACE=1` for a backtrace.
error: Process didn't exit successfully: `target/debug/examples/demo piano.wav` (exit code: 101)

Process finished with exit code 101

I've brew installed the following packages:

brew list --versions
sdl2 2.0.4
sdl2_mixer 2.0.1

Was there some kind of configuration step I've missed?

Environment:

OSX 10.11.6
Rust stable 1.12.1
Cargo 0.13.0
Homebrew 1.0.8

Create a branch using sdl2 git?

There is a problem when you have two different versions of sdl2 among the dependencies:

Project X -> sdl2
Project X -> sdl2_mixer -> sdl2

When something in Rust breaks, the sdl2 cargo registry version must be updated and then sdl2_mixer, which takes more time than updating the git dependencies directly.

Upgrade to latest Rust

src/sdl2_mixer/lib.rs:265:44: 265:45 error: obsolete syntax: `|uint| -> bool` closure type syntax
src/sdl2_mixer/lib.rs:265                 let cb = mem::transmute::<_, |Channel|>(cb);
                                                                     ^
note: use unboxed closures instead, no type annotation needed
src/sdl2_mixer/lib.rs:273:30: 273:31 error: obsolete syntax: `|uint| -> bool` closure type syntax
src/sdl2_mixer/lib.rs:273 pub fn set_channel_finished(f: |Channel|:'static) {
                                                       ^
src/sdl2_mixer/lib.rs:593:39: 593:40 error: obsolete syntax: `|uint| -> bool` closure type syntax
src/sdl2_mixer/lib.rs:593             let f = mem::transmute::<_, ||>(f);
                                                                ^
src/sdl2_mixer/lib.rs:746:27: 746:28 error: obsolete syntax: `|uint| -> bool` closure type syntax
src/sdl2_mixer/lib.rs:746     pub fn hook_finished(f: ||) {
                                                    ^
error: aborting due to 4 previous errors
Could not compile `sdl2_mixer`.

Problem playing short sound sample chunk

I've been attempting to load and play a sound sample using sdl2_mixer in sdl2 but have been having problems.

Here is a short example snippet which should compile and run.
It requires a .wav sound file named "Example.wav" to test.

extern crate sdl2;
extern crate sdl2_mixer;

#[start]
fn start(argc: int, argv: **u8) -> int {
    native::start(argc, argv, main)
}

#[main]
fn main() {
    if !(sdl2::init(sdl2::InitAudio | sdl2::InitTimer)) {
        fail!("Could not initialize SDL2!");
    }

    println!("inited => {}", sdl2_mixer::init(sdl2_mixer::InitMp3 | sdl2_mixer::InitFlac |
                             sdl2_mixer::InitMod | sdl2_mixer::InitFluidSynth |
                             sdl2_mixer::InitModPlug | sdl2_mixer::InitOgg).get());

    sdl2_mixer::open_audio(sdl2_mixer::DEFAULT_FREQUENCY, 0x8010u16, 2, 1024).unwrap();
    sdl2_mixer::allocate_channels(1);

    let sound = sdl2_mixer::Chunk::from_file(&Path::new("Example.wav")).unwrap();

    let channel = sdl2_mixer::Channel::all();
    channel.play(sound, 0).unwrap();

    sdl2::timer::delay(3000);

    sdl2_mixer::quit();
    sdl2::quit();
}

When executed, the program outputs
task '<main>' failed at 'called Result::unwrap()on anErr value: Unrecognized sound file type', /home/rustbuild/src/rust-buildbot/slave/nightly-linux/build/src/libstd/result.rs:298
In addition, the Example.wav sound file gets wiped to 0B.

Before running the program, I am able to play Example.wav in several audio players, this problem also occurs with other sound files I try to run, so I don't think this is a problem with the sound files themselves.

Is this the correct way to load and play short sound samples in rust-sdl2_mixer?

Also, could the demo section contain an example of loading and playing chunk sound samples?

Undefined behavior when dropping Music after mix_quit has been called

If you call mix::quit before dropping a Music, dropping it will trigger undefined behavior and causes a segmentation fault on my system.

This is unacceptable, as this can be caused by safe Rust code.

One solution is to just let the music leak if the library is not initialized anymore.

Another solution is to change the architecture of the library, as was done with rust-sdl2, to be able to tie the lifetime of a music to the lifetime of the sdl2_mixer context.

I haven't checked, but this issue most likely also applies to Chunk and maybe some other types that implement Drop.

Here is a minimal test case:

extern crate sdl2 as sdl;
extern crate sdl2_mixer as mix;

fn main() {
    let _sdl_ctx = sdl::init().everything().unwrap();
    mix::init(mix::INIT_MODPLUG);
    mix::open_audio(mix::DEFAULT_FREQUENCY, mix::DEFAULT_FORMAT, 2, 4096).unwrap();
    // http://modarchive.org/index.php?request=view_by_moduleid&query=96492
    let mus = mix::Music::from_file("sdv_3.mod".as_ref()).unwrap();
    mus.play(0).unwrap();
    ::std::thread::sleep_ms(3000);
    mix::quit();
}