play method

void play({
  1. required Sound sound,
  2. String? customSound,
  3. String? packageName,
  4. bool? isLooping = false,
})

Plays sound, or customSound from packageName's assets.

Sound.incomingCall rings as an incoming call: on the incoming ringtone's own player, with the vibration, following the phone's ring settings as the incoming call banner does (see CometChatIncomingCall.disableSoundForCalls). For it, customSound is looked for in packageName's assets, then in the app's own, and the UI Kit's ringtone plays when it is not found. It plays once unless isLooping.

Every other sound plays on the message sounds' player, as before 6.2.0: packageName is not used to find a customSound there, and on iOS the UI Kit's own message and call sounds may not be found.

While an incoming call rings, the sounds that play once are skipped, not queued: the message sounds, and a one-shot Sound.incomingCall. On one shared player they used to replace the ringtone for good, and a ding over a ringing phone helps no one. A looping sound still plays (a looping Sound.incomingCall takes the ringtone over). This holds with the phone in Silent or Vibrate mode too, and it does not apply while a banner rings with disableSoundForCalls: it rings nothing.

Implementation

void play({
  required Sound sound,
  String? customSound,
  String? packageName, // Use it only when using other plugin
  bool? isLooping = false,
}) async {
  if (kIsWeb) return;

  if (sound == Sound.incomingCall) {
    // A one-shot ringtone over an incoming call ringing now would replace
    // its looping ringtone on the one native player, for good, and its
    // end would give the audio back while the call still rang.
    if (isLooping != true && IncomingRingtone.isRinging) {
      ccLog('SoundManager: $sound not played, an incoming call is ringing');
      return;
    }
    final bool custom = customSound != null && customSound.isNotEmpty;
    await IncomingRingtone.play(
      assetPath: customSound,
      package: custom ? packageName : null,
      looping: isLooping == true,
      // A ringtone that plays once rings no one's phone for long: only a
      // looping one holds the message sounds back.
      owner: isLooping == true ? _hostRingtone : null,
    );
    return;
  }

  if (isLooping != true && IncomingRingtone.isRinging) {
    ccLog('SoundManager: $sound not played, an incoming call is ringing');
    return;
  }

  String soundPath = "";

  if (customSound != null && customSound.isNotEmpty) {
    soundPath = customSound;
  } else {
    soundPath = _getDefaultSoundPath(sound);
    packageName ??= UIConstants.packageName;
    if (platform.platformIsAndroid()) {
      soundPath = "packages/$packageName/$soundPath";
    }
  }
  try {
    await UIConstants.channel.invokeMethod("playCustomSound", {
      'assetAudioPath': soundPath,
      'package': packageName,
      'isLooping': isLooping,
    });
  } catch (e) {
    if (e.toString().contains('AUDIO_FOCUS_FAILED')) {
      ccLog('Audio focus not available. Notification sound skipped.');
    } else {
      ccLog('Error playing sound: $e');
    }
  }
}