smbale / ambience

Ambience

The Simplest Audio Player Service Library for Android

Introduction

Ambience is a small and powerful android library that helps you build advanced audio apps in minutes. Built upon many of android's system components and powerful open source libraries, Ambience is fast, efficient and easy to use.

Ambience is compatible with android mobile, tv and auto. Pass Ambience a playlist filled with tracks then lean back and relax. Ambience will continue to play audio even when the app is placed in the background.

Ambience.turnOn(context)
        .setPlaylistTo(playlist)
        .play();

Features

Playback Controls

Customize and play any playlist with just one line of code. Play, Skip, Forward, Rewind, Pause and Volume Control are just a few of the playback controls that Ambience provides.

Ambience.activeInstance()
        .shuffleAndSetPlaylistTo(playlist)
        .setVolumeTo(0.5f)
        .playFromPosition(3);

Custom Notifications

Ambience creates a custom notification for each track in the playlist. Users can use these notifications to control playback options and jump right back into your app. Notifications created by Ambience will also show up on wearable devices that are connected to the app. For android tv and auto apps, a notification will show as a now playing card in the recommendation section.

To launch an activity from a notification, pass a unique Intent-Filter action name.

Ambience.activeInstance().setNotificationLaunchActivity(actionName);

Callback Methods

Get notified when an event occurs or playback options change via the AmbientListener interface. The AmbientListener provides several callback methods that are triggered for the current playing track or when an event occurs in the service.

Ambience.activeInstance().listenForUpdatesWith(AmbientListener);

AmbientTrack

Store track meta data with the AmbientTrack class. The AmbientTrack class extends on the android's Parcelable class. This allows an AmbientTrack to be easily integrated or shared between projects.

public void bindView(View view, Parcelable object) {
    AmbientTrack track = (AmbientTrack) object;
   ((TextView) view).setText(track.getName());
}

How it Works

Ambience - A BroadcastReceiver that sends and receivers request from the AmbientService. This class provides methods for controlling audio playback. Ambience will trigger update methods on a callback object that has implemented the AmbientListener interface.

AmbientService - An Android Service that allows audio playback in the background. The AmbientService listens for a request, performs the request on the current playlist and alerts the Ambience class when done.

AmbientTrack - A class that holds meta data for a single track.

AmbientListener - A callback interface that is triggered when an event has occurred in the AmbientService.

Version

Current Version == v1.5

Visit the Ambience Website for more information.

Sample Code

Get the sample code here.

Contribute

Before submitting a request, please make sure that your code runs on an android device.

License

Copyright 2014 TonyoStudios.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Disclaimer

The Ambience Library uses Picasso a powerful image downloading and caching library for android. Picasso is property of Square Inc and is provided under the Apache 2.0 License. Visit square.github.io/Picasso for more information.