JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 163
  • Score
    100M100P100Q73120F
  • License Apache-2.0

NativeScript plugin to record and play audio.

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@nativescript-community/audio) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    @nativescript-community/audio

    Downloads per month NPM Version

    NativeScript plugin to record and play audio.


    iOS Demo Android Demo

    Table of Contents

    Installation

    Run the following command from the root of your project:

    ns plugin add @nativescript-community/audio

    Installation

    ns plugin add @nativescript-community/audio

    Android Native Classes

    iOS Native Classes

    Permissions

    iOS

    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>

    Android

    If you are going to use the recorder capability for Android, you need to add the RECORD_AUDIO permission to your AndroidManifest.xml file located in App_Resources.

        <uses-permission android:name="android.permission.RECORD_AUDIO"/>

    Usage

    TypeScript Example

    import { TNSPlayer } from '@nativescript-community/audio';
    
    export class YourClass {
      private _player: TNSPlayer;
    
      constructor() {
        this._player = new TNSPlayer();
        // You can pass a duration hint to control the behavior of other application that may
        // be holding audio focus.
        // For example: new  TNSPlayer(AudioFocusDurationHint.AUDIOFOCUS_GAIN_TRANSIENT);
        // Then when you play a song, the previous owner of the
        // audio focus will stop. When your song stops
        // the previous holder will resume.
        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-community/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(res => {
        console.log(res);
      })
      .catch(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 of track (in seconds).
    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

    Demos and Development

    Setup

    To run the demos, you must clone this repo recursively.

    git clone https://github.com/@nativescript-community/audio.git --recursive

    Install Dependencies:

    npm i # or 'yarn install' or 'pnpm install'

    Interactive Menu:

    To start the interactive menu, run npm start (or yarn start or pnpm start). This will list all of the commonly used scripts.

    Build

    npm run build
    
    npm run build.angular # or for Angular

    Demos

    npm run demo.[ng|react|svelte|vue].[ios|android]
    
    npm run demo.svelte.ios # Example

    Questions

    If you have any questions/issues/comments please feel free to create an issue or start a conversation in the NativeScript Community Discord.