android-sdd 1.0.0

package/skills/Google Ecosystem/Firebase Messaging/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: firebase-messaging
+description: >
+  Firebase Cloud Messaging (FCM) setup and handling for Android.
+  Load this skill when implementing push notifications, handling FCM tokens,
+  processing foreground/background messages, or sending data payloads.
+---
+
+# Firebase Messaging (FCM)
+
+## Overview
+Firebase Cloud Messaging (FCM) is Google's cross-platform messaging solution for push notifications. It delivers notification messages (shown by system) and data messages (handled by app code) to Android devices. FCM tokens identify each device/app installation.
+
+---
+
+## Core Principles
+
+- **Notification messages** — shown automatically by system when app is in background
+- **Data messages** — always delivered to `onMessageReceived()` for app to handle
+- FCM token can change — always update the server when token refreshes
+- Notification permission is required on **API 33+** — `POST_NOTIFICATIONS`
+- Handle messages in a **short time** — `onMessageReceived()` has ~10 second limit
+
+---
+
+## Setup
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation(platform(libs.firebase.bom))
+    implementation(libs.firebase.messaging)
+}
+```
+
+```xml
+<!-- AndroidManifest.xml -->
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+<service
+    android:name=".messaging.MyFirebaseMessagingService"
+    android:exported="false">
+    <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+    </intent-filter>
+</service>
+```
+
+---
+
+## MessagingService Implementation
+
+```kotlin
+// ✅ Handle incoming messages and token refresh
+class MyFirebaseMessagingService : FirebaseMessagingService() {
+
+    @Inject
+    lateinit var notificationManager: AppNotificationManager
+
+    @Inject
+    lateinit var tokenRepository: FcmTokenRepository
+
+    // ✅ Called when a new FCM token is generated
+    override fun onNewToken(token: String) {
+        super.onNewToken(token)
+        // Upload new token to your server
+        CoroutineScope(SupervisorJob() + Dispatchers.IO).launch {
+            tokenRepository.updateToken(token)
+        }
+    }
+
+    // ✅ Called for all messages when app is in foreground
+    // Called for data-only messages when app is in background
+    override fun onMessageReceived(message: RemoteMessage) {
+        super.onMessageReceived(message)
+
+        val title = message.notification?.title ?: message.data["title"] ?: return
+        val body  = message.notification?.body  ?: message.data["body"]  ?: return
+        val type  = message.data["type"]
+        val id    = message.data["id"]
+
+        notificationManager.showNotification(
+            title = title,
+            body = body,
+            data = message.data
+        )
+    }
+}
+```
+
+---
+
+## FCM Token Management
+
+```kotlin
+// ✅ Get current token
+class FcmTokenRepository @Inject constructor(
+    private val api: UserApi,
+    private val prefs: DataStore<Preferences>
+) {
+    suspend fun getToken(): String? = suspendCoroutine { cont ->
+        FirebaseMessaging.getInstance().token
+            .addOnSuccessListener { cont.resume(it) }
+            .addOnFailureListener { cont.resume(null) }
+    }
+
+    suspend fun updateToken(token: String) {
+        val saved = prefs.data.first()[FCM_TOKEN_KEY]
+        if (saved != token) {
+            api.updateFcmToken(token)
+            prefs.edit { it[FCM_TOKEN_KEY] = token }
+        }
+    }
+
+    suspend fun deleteToken() {
+        FirebaseMessaging.getInstance().deleteToken().await()
+        api.deleteFcmToken()
+        prefs.edit { it.remove(FCM_TOKEN_KEY) }
+    }
+
+    companion object {
+        val FCM_TOKEN_KEY = stringPreferencesKey("fcm_token")
+    }
+}
+```
+
+---
+
+## Notification Permission (API 33+)
+
+```kotlin
+// ✅ Request POST_NOTIFICATIONS permission on Android 13+
+@Composable
+fun NotificationPermissionHandler(onGranted: () -> Unit) {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+        val permissionState = rememberPermissionState(
+            Manifest.permission.POST_NOTIFICATIONS
+        )
+        LaunchedEffect(Unit) {
+            if (!permissionState.status.isGranted) {
+                permissionState.launchPermissionRequest()
+            } else {
+                onGranted()
+            }
+        }
+    } else {
+        LaunchedEffect(Unit) { onGranted() }
+    }
+}
+```
+
+---
+
+## Showing Notifications
+
+```kotlin
+// ✅ NotificationManager wrapper
+class AppNotificationManager @Inject constructor(
+    private val context: Context
+) {
+    private val notificationManager =
+        context.getSystemService(NotificationManager::class.java)
+
+    init {
+        createChannels()
+    }
+
+    private fun createChannels() {
+        val channel = NotificationChannel(
+            CHANNEL_ID_GENERAL,
+            "General",
+            NotificationManager.IMPORTANCE_DEFAULT
+        ).apply {
+            description = "General app notifications"
+        }
+        notificationManager.createNotificationChannel(channel)
+    }
+
+    fun showNotification(title: String, body: String, data: Map<String, String>) {
+        val intent = Intent(context, MainActivity::class.java).apply {
+            flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
+            data.forEach { (key, value) -> putExtra(key, value) }
+        }
+
+        val pendingIntent = PendingIntent.getActivity(
+            context, 0, intent,
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        )
+
+        val notification = NotificationCompat.Builder(context, CHANNEL_ID_GENERAL)
+            .setSmallIcon(R.drawable.ic_notification)
+            .setContentTitle(title)
+            .setContentText(body)
+            .setAutoCancel(true)
+            .setContentIntent(pendingIntent)
+            .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+            .build()
+
+        notificationManager.notify(System.currentTimeMillis().toInt(), notification)
+    }
+
+    companion object {
+        const val CHANNEL_ID_GENERAL = "general"
+    }
+}
+```
+
+---
+
+## Message Types
+
+```kotlin
+// Notification message (server-sent):
+// {
+//   "notification": { "title": "Hello", "body": "World" },
+//   "to": "<fcm_token>"
+// }
+// → System shows notification automatically when app in background
+// → onMessageReceived() called when app in foreground
+
+// Data message (server-sent):
+// {
+//   "data": { "title": "Hello", "body": "World", "type": "order_update" },
+//   "to": "<fcm_token>"
+// }
+// → onMessageReceived() always called regardless of app state
+
+// ✅ Prefer data messages for full control over display
+```
+
+---
+
+## Topic Subscription
+
+```kotlin
+// ✅ Subscribe to topics for broadcast messages
+suspend fun subscribeToTopic(topic: String) {
+    FirebaseMessaging.getInstance().subscribeToTopic(topic).await()
+}
+
+suspend fun unsubscribeFromTopic(topic: String) {
+    FirebaseMessaging.getInstance().unsubscribeFromTopic(topic).await()
+}
+
+// Usage
+subscribeToTopic("promotions")
+subscribeToTopic("user_${userId}")
+```
+
+---
+
+## Anti-Patterns
+
+- Not updating token on `onNewToken()` — server sends to stale token, messages lost
+- Long-running work in `onMessageReceived()` — only 10 seconds available; use WorkManager
+- Notification messages for data that needs app processing — use data messages
+- Not creating notification channels — notifications silently dropped on API 26+
+- Not handling `POST_NOTIFICATIONS` permission on API 33+ — no notifications shown
+
+---
+
+## Related Skills
+- `firebase` — Firebase core setup
+- `notification` — notification channels and display
+- `workmanager` — background work triggered by FCM
+- `deep-link` — navigating to specific screen from notification tap

package/skills/Media/Audio/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: audio
+description: >
+  Android audio playback and recording patterns.
+  Load this skill when playing audio files, recording from microphone,
+  managing audio focus, or handling audio streams in Android.
+---
+
+# Audio
+
+## Overview
+Android provides multiple APIs for audio — `MediaPlayer` for simple playback, `AudioTrack` for low-latency PCM, `MediaRecorder` for recording, and `AudioRecord` for raw PCM capture. Choosing the right API depends on the use case: streaming, local file, or real-time processing.
+
+---
+
+## Core Principles
+
+- Always **request audio focus** before playback — respect other apps
+- **Release resources** (`MediaPlayer`, `MediaRecorder`) when done — they hold hardware
+- Audio operations that block belong on **Dispatchers.IO**
+- Handle **audio output changes** (headphone unplug, Bluetooth) — pause when needed
+- Declare `RECORD_AUDIO` permission for recording — runtime permission required
+
+---
+
+## Permissions
+
+```xml
+<!-- AndroidManifest.xml -->
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+```
+
+---
+
+## MediaPlayer — Simple Playback
+
+```kotlin
+// ✅ Play from resource
+class AudioPlayer(private val context: Context) {
+
+    private var mediaPlayer: MediaPlayer? = null
+
+    fun playFromResource(@RawRes resId: Int) {
+        release()
+        mediaPlayer = MediaPlayer.create(context, resId).apply {
+            setOnCompletionListener { release() }
+            start()
+        }
+    }
+
+    // ✅ Play from URL (streaming)
+    fun playFromUrl(url: String) {
+        release()
+        mediaPlayer = MediaPlayer().apply {
+            setAudioAttributes(
+                AudioAttributes.Builder()
+                    .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
+                    .setUsage(AudioAttributes.USAGE_MEDIA)
+                    .build()
+            )
+            setDataSource(url)
+            setOnPreparedListener { start() }
+            setOnErrorListener { _, what, extra ->
+                Log.e("AudioPlayer", "Error: what=$what extra=$extra")
+                true
+            }
+            prepareAsync()  // ✅ Non-blocking prepare for streams
+        }
+    }
+
+    fun pause() { mediaPlayer?.pause() }
+    fun resume() { mediaPlayer?.start() }
+    fun stop() { mediaPlayer?.stop() }
+
+    // ✅ Always release — frees hardware resource
+    fun release() {
+        mediaPlayer?.release()
+        mediaPlayer = null
+    }
+}
+```
+
+---
+
+## Audio Focus
+
+```kotlin
+// ✅ Request audio focus before playback
+class AudioFocusManager(private val context: Context) {
+
+    private val audioManager = context.getSystemService(AudioManager::class.java)
+    private var focusRequest: AudioFocusRequest? = null
+
+    fun requestFocus(onGranted: () -> Unit, onLost: () -> Unit): Boolean {
+        val request = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
+            .setAudioAttributes(
+                AudioAttributes.Builder()
+                    .setUsage(AudioAttributes.USAGE_MEDIA)
+                    .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
+                    .build()
+            )
+            .setOnAudioFocusChangeListener { focusChange ->
+                when (focusChange) {
+                    AudioManager.AUDIOFOCUS_LOSS           -> onLost()
+                    AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> onLost()  // pause temporarily
+                    AudioManager.AUDIOFOCUS_GAIN           -> onGranted() // resume
+                }
+            }
+            .build()
+
+        focusRequest = request
+        val result = audioManager.requestAudioFocus(request)
+        return result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED
+    }
+
+    fun abandonFocus() {
+        focusRequest?.let { audioManager.abandonAudioFocusRequest(it) }
+        focusRequest = null
+    }
+}
+```
+
+---
+
+## Handle Headphone Unplug
+
+```kotlin
+// ✅ Pause when headphones are disconnected
+class NoisyReceiver(private val onBecomingNoisy: () -> Unit) : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action == AudioManager.ACTION_AUDIO_BECOMING_NOISY) {
+            onBecomingNoisy()  // pause playback
+        }
+    }
+}
+
+// Register/unregister with lifecycle
+override fun onStart() {
+    super.onStart()
+    val filter = IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY)
+    registerReceiver(noisyReceiver, filter)
+}
+
+override fun onStop() {
+    unregisterReceiver(noisyReceiver)
+    super.onStop()
+}
+```
+
+---
+
+## MediaRecorder — Simple Recording
+
+```kotlin
+// ✅ Record audio to file
+class AudioRecorder(private val context: Context) {
+
+    private var recorder: MediaRecorder? = null
+
+    fun startRecording(outputFile: File) {
+        recorder = MediaRecorder(context).apply {
+            setAudioSource(MediaRecorder.AudioSource.MIC)
+            setOutputFormat(MediaRecorder.OutputFormat.MPEG_4)
+            setAudioEncoder(MediaRecorder.AudioEncoder.AAC)
+            setAudioSamplingRate(44100)
+            setAudioEncodingBitRate(128_000)
+            setOutputFile(outputFile.absolutePath)
+            prepare()
+            start()
+        }
+    }
+
+    fun stopRecording(): File? {
+        return try {
+            recorder?.apply {
+                stop()
+                release()
+            }
+            recorder = null
+            outputFile
+        } catch (e: Exception) {
+            null
+        }
+    }
+
+    fun release() {
+        recorder?.release()
+        recorder = null
+    }
+}
+```
+
+---
+
+## AudioRecord — Raw PCM Capture
+
+```kotlin
+// ✅ For real-time audio processing (speech recognition, audio analysis)
+class RawAudioCapture {
+
+    private val sampleRate = 44100
+    private val bufferSize = AudioRecord.getMinBufferSize(
+        sampleRate,
+        AudioFormat.CHANNEL_IN_MONO,
+        AudioFormat.ENCODING_PCM_16BIT
+    )
+
+    private var audioRecord: AudioRecord? = null
+    private var isRecording = false
+
+    fun startCapture(onAudioData: (ShortArray) -> Unit) {
+        audioRecord = AudioRecord(
+            MediaRecorder.AudioSource.MIC,
+            sampleRate,
+            AudioFormat.CHANNEL_IN_MONO,
+            AudioFormat.ENCODING_PCM_16BIT,
+            bufferSize
+        )
+
+        isRecording = true
+        audioRecord?.startRecording()
+
+        Thread {
+            val buffer = ShortArray(bufferSize)
+            while (isRecording) {
+                val read = audioRecord?.read(buffer, 0, buffer.size) ?: 0
+                if (read > 0) onAudioData(buffer.copyOf(read))
+            }
+        }.start()
+    }
+
+    fun stopCapture() {
+        isRecording = false
+        audioRecord?.stop()
+        audioRecord?.release()
+        audioRecord = null
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Not releasing `MediaPlayer` or `MediaRecorder` — holds hardware, other apps can't use it
+- Playing audio without requesting audio focus — overlaps with other apps' audio
+- `prepare()` instead of `prepareAsync()` for network streams — blocks main thread
+- Not handling `AudioManager.ACTION_AUDIO_BECOMING_NOISY` — audio leaks from speaker
+- Recording without checking/requesting `RECORD_AUDIO` permission
+
+---
+
+## Related Skills
+- `exoplayer` — advanced media playback
+- `foreground-service` — background audio playback
+- `lifecycle` — releasing audio resources with lifecycle
+- `manifest` — audio permission declaration