NativeScript-Audio

NativeScript plugin to play and record audio files for Android and iOS.

Installation

The plugin is compatible with both Nativescript 3.x and 2.x versions. Install with:

tns plugin add nativescript-audio

---

Android Native Classes

• Player - android.media.MediaPlayer
• Recorder - android.media.MediaRecorder

iOS Native Classes

• Player - AVAudioPlayer
• Recorder - AVAudioRecorder

Note: You will need to grant permissions on iOS to allow the device to access the microphone if you are using the recording function. If you don't, your app may crash on device and/or your app might be rejected during Apple's review routine. To do this, add this key to your app/App_Resources/iOS/Info.plist file:

<key>NSMicrophoneUsageDescription</key>
<string>Recording Practice Sessions</string>

Usage

TypeScript Example

import { TNSPlayer } from "nativescript-audio";

export class YourClass {
  private _player: TNSPlayer;

  constructor() {
    this._player = new TNSPlayer();
    this._player.debug = true; // set true to enable TNSPlayer console logs for debugging.
    this._player
      .initFromFile({
        audioFile: "~/audio/song.mp3", // ~ = app directory
        loop: false,
        completeCallback: this._trackComplete.bind(this),
        errorCallback: this._trackError.bind(this)
      })
      .then(() => {
        this._player.getAudioTrackDuration().then(duration => {
          // iOS: duration is in seconds
          // Android: duration is in milliseconds
          console.log(`song duration:`, duration);
        });
      });
  }

  public togglePlay() {
    if (this._player.isAudioPlaying()) {
      this._player.pause();
    } else {
      this._player.play();
    }
  }

  private _trackComplete(args: any) {
    console.log("reference back to player:", args.player);
    // iOS only: flag indicating if completed succesfully
    console.log("whether song play completed successfully:", args.flag);
  }

  private _trackError(args: any) {
    console.log("reference back to player:", args.player);
    console.log("the error:", args.error);
    // Android only: extra detail on error
    console.log("extra info on the error:", args.extra);
  }
}

Javascript Example:

const audio = require("nativescript-audio");

const player = new audio.TNSPlayer();
const playerOptions = {
  audioFile: "http://some/audio/file.mp3",
  loop: false,
  completeCallback: function() {
    console.log("finished playing");
  },
  errorCallback: function(errorObject) {
    console.log(JSON.stringify(errorObject));
  },
  infoCallback: function(args) {
    console.log(JSON.stringify(args));
  }
};

player
  .playFromUrl(playerOptions)
  .then(function(res) {
    console.log(res);
  })
  .catch(function(err) {
    console.log("something went wrong...", err);
  });

API

Recorder

TNSRecorder Methods

Method	Description
TNSRecorder.CAN_RECORD(): boolean - static method	Determine if ready to record.
start(options: AudioRecorderOptions): Promise<void>	Start recording to file.
stop(): Promise<void>	Stop recording.
pause(): Promise<void>	Pause recording.
resume(): Promise<void>	Resume recording.
dispose(): Promise<void>	Free up system resources when done with recorder.
getMeters(channel?: number): number	Returns the amplitude of the input.
isRecording(): boolean - iOS Only	Returns true if recorder is actively recording.
requestRecordPermission(): Promise<void>	Android Only Resolves the promise is user grants the permission.
hasRecordPermission(): boolean	Android Only Returns true if RECORD_AUDIO permission has been granted.

TNSRecorder Instance Properties

Property	Description
ios	Get the native AVAudioRecorder class instance.
android	Get the native MediaRecorder class instance.
debug	Set true to enable debugging console logs (default false).

Player

TNSPlayer Methods

Method	Description
initFromFile(options: AudioPlayerOptions): Promise	Initialize player instance with a file without auto-playing.
playFromFile(options: AudioPlayerOptions): Promise	Auto-play from a file.
initFromUrl(options: AudioPlayerOptions): Promise	Initialize player instance from a url without auto-playing.
playFromUrl(options: AudioPlayerOptions): Promise	Auto-play from a url.
pause(): Promise<boolean>	Pause playback.
resume(): void	Resume playback.
seekTo(time:number): Promise<boolean>	Seek to position.
dispose(): Promise<boolean>	Free up resources when done playing audio.
isAudioPlaying(): boolean	Determine if player is playing.
getAudioTrackDuration(): Promise<string>	Duration of media file assigned to the player.
playAtTime(time: number): void - iOS Only	Play audio track at specific time of duration.
changePlayerSpeed(speed: number): void - On Android Only API 23+	Change the playback speed of the media player.

TNSPlayer Instance Properties

Property	Description
ios	Get the native ios AVAudioPlayer instance.
android	Get the native android MediaPlayer instance.
debug: boolean	Set true to enable debugging console logs (default false).
currentTime: number	Get the current time in the media file's duration.
volume: number	Get/Set the player volume. Value range from 0 to 1.

License

MIT