Skip to content

Updated README.md (added Installing information, contribution instructions, unit testing instructions) #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Updated README.md (added Installing information, contribution instructions, unit testing instructions) #30

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 145 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@

[license]: https://github.com/treefortress/SoundAS/raw/master/license.txt

SoundAS - AS3 SoundManager
Expand All @@ -7,7 +8,18 @@ A modern lightweight AS3 SoundManager for Flash and AIR.

The goal of SoundAS is to simplifying playback of your audio files, with a focus on easily transitioning from one to another, and differentiating between SoundFX and Music Loops.

#Features
# Table of Contents

- [Features](#features)
- [API Overview](#api-overview)
- [Installation](#installation)
- [Code Examples](#code-examples)
- [Advanced Examples](#advanced-examples)
- [Contribution Guide](#contribution-guide)
- [Unit Testing](#unit-testing)
- [License](#license)

# Features
* Clean modern API
* API Chaining: SoundAS.play("music").fadeTo(0);
* Supports groups of sounds
Expand All @@ -17,11 +29,19 @@ The goal of SoundAS is to simplifying playback of your audio files, with a focus
* Modular API: Use SoundInstance directly and ignore the rest.
* Non-restrictive and unambigous license

#API Overview
The following file formats are supported by SoundAS for audio playback:

- MP3
- WAV
- OGG/Vorbis
- M4A (AAC)
- FLAC
Note that other formats may be supported but may require additional libraries to be installed.
# API Overview

Full documentation can be found here: http://treefortress.com/libs/SoundAS/docs/.

###SoundAS
### SoundAS
This Class is the main interface for the library. It's responsible for loading and controlling all sounds globally.

Loading / Unloading:
Expand Down Expand Up @@ -50,7 +70,7 @@ Playback:
* **SoundAS.fadeAllTo**(endVolume:Number = 1, duration:Number = 1000):SoundInstance
* **SoundAS.fadeMasterTo**(endVolume:Number = 1, duration:Number = 1000)

####SoundInstance
#### SoundInstance
Controls playback of individual sounds, allowing you to easily stop, start, resume and set volume or position.

* **play**(volume:Number = 1, startTime:Number = 0, loops:int = 0, allowMultiple:Boolean = true):SoundInstance
Expand All @@ -64,17 +84,26 @@ Controls playback of individual sounds, allowing you to easily stop, start, resu
* **destroy**():void
* **endFade**(applyEndVolume:Boolean = false):SoundInstance

#Code Examples

###Loading
# Installation
To install SoundAS locally on your computer, you can follow these steps:

1. Download the latest version of SoundAS from the official GitHub repository: [https://github.com/treefortress/SoundAS/releases](https://github.com/treefortress/SoundAS/releases "https://github.com/treefortress/SoundAS/releases")
2. Extract the downloaded ZIP file to a location of your choice.
3. In your Flash or AIR project, add the extracted SoundAS SWC file to your library path.
4. Finally, import the SoundAS classes you need in your project.

# Code Examples

### Loading

//Load sound from an external file
SoundAS.loadSound("assets/Click.mp3", "click");

//Inject an already loaded Sound instance
SoundAS.addSound("click", clickSound);

###Basic Playback
### Basic Playback

//Play sound.
//allowMultiple: Allow multiple overlapping sound instances.
Expand Down Expand Up @@ -103,7 +132,34 @@ Controls playback of individual sounds, allowing you to easily stop, start, resu

//Fade masterVolume out
SoundAS.fadeMasterTo(0);

### Slowing down and speeding up audio:
```
// Load the sound
SoundAS.loadSound("mySound.mp3", "mySound");

// Get the sound data as a ByteArray
var soundData:ByteArray = SoundAS.getSound("mySound").data;

// Set the playback speed to half (0.5)
soundData.position = 0;
var sound:Sound = new Sound();
sound.loadPCMFromByteArray(soundData, soundData.length);
var channel:SoundChannel = sound.play();
channel.soundTransform = new SoundTransform(0.5);
```
### Changing Volume:
```
// Load the sound
SoundAS.loadSound("mySound.mp3", "mySound");

// Play the sound at half volume
var soundInstance:SoundInstance = SoundAS.play("mySound");
soundInstance.volume = 0.5;
```

Remember to thoroughly test your changes and ensure they adhere to project standards. Your commitment to maintaining code quality and functionality is greatly appreciated. Thank you for contributing to SoundAS!

## Advanced Examples
### Groups

//Create a group
Expand All @@ -125,7 +181,7 @@ Controls playback of individual sounds, allowing you to easily stop, start, resu
SoundAS.groups[i].stopAll();
}

###Advanced
### Misc Advanced

//Mute one sound
SoundsAS.getSound("click").mute = true;
Expand Down Expand Up @@ -153,7 +209,85 @@ Controls playback of individual sounds, allowing you to easily stop, start, resu
}
}

---


## Contribution Guide

Thank you for your interest in contributing to SoundAS! To get started, follow these steps:

### 1. Fork the Repository

Click the "Fork" button at the top-right corner of the repository's page. This will create a copy of the repository in your GitHub account.

### 2. Clone Your Fork

Clone your forked repository to your local machine:

```
git clone https://github.com/<your-username>/SoundAS.git
```


### 3. Create a New Branch

Create a new branch for your contribution:

```
git checkout -b feature/new-feature
```


### 4. Make Your Changes

Make the necessary changes to the codebase to fix whatever issue you are attempting to solve.

### 5. Test Your Changes

Before submitting your contribution, it's important to test your changes. Verify that your modifications work as expected and do not introduce new issues. Be sure to include relevant tests to validate your code. If applicable, update existing tests to cover your changes.

### 6. Commit Your Changes

Commit your changes with a clear and concise commit message:



```
git commit -m "Add new feature: description of your changes"
```


### 7. Push Your Changes

Push your changes to your forked repository:

```
git push origin feature/new-feature
```


### 8. Create a Pull Request

Return to the [repository](https://github.com/treefortress/SoundAS) and create a pull request (PR). Provide a brief description of your changes and any relevant context. Ensure that your PR title and description are clear and informative.

### 9. Review and Collaboration

Project maintainers will review your PR. They may provide feedback or request changes. Be responsive to comments or requests for clarification.

### 10. Celebrate Your Contribution

Once your contribution is accepted and merged into the project, your work becomes part of SoundAS. Congratulations on your successful contribution!

----------

Remember to thoroughly test your changes and ensure they adhere to project standards. Your commitment to maintaining code quality and functionality is greatly appreciated. Thank you for contributing to SoundAS!

## Unit Testing:
To run unit tests on SoundAS, you can follow these steps:

1. Clone the SoundAS repository from GitHub: [https://github.com/treefortress/SoundAS](https://github.com/treefortress/SoundAS "https://github.com/treefortress/SoundAS")
2. Open the repository in Visual Studio Code.
3. Open the integrated terminal in Visual Studio Code.
4. Run the command `npm install` to install the required dependencies.
5. Run the command `npm test` to run the unit tests.
### License
[WTFPL][license]