refactor: unify audio header and tag fields into TrackMetadata

Author: zeevenn

README.md

@@ -95,23 +95,54 @@ Promise that resolves to `TrackResult` containing:
 - `endCursor`: String cursor for pagination
 - `totalCount`: Total number of tracks (optional)
 
-#### Example
+### getTrackMetadataAsync(trackId)
 
-```js
-import { getTracksAsync } from '@nodefinity/react-native-music-library';
+Retrieves detailed metadata for a specific track, including lyrics and additional metadata from JAudioTagger.
 
-// Get first 20 tracks (default)
-const result = await getTracksAsync();
+#### Parameters
 
-// Get tracks with custom options
-const customResult = await getTracksAsync({
-  first: 50,
-  sortBy: ['title', true], // Sort by title ascending
-  directory: '/Music/Favorites'
-});
+- `trackId`: string - The ID of the track to get metadata for
+
+#### Returns
+
+Promise that resolves to `TrackMetadata` containing:
+
+```typescript
+interface TrackMetadata {
+  id: string;              // Track ID
+
+  // audio header
+  duration?: number;       // Duration in seconds
+  bitrate?: number;        // Bitrate in kbps
+  sampleRate?: number;     // Sample rate in Hz
+  channels?: number;       // Number of channels
+  format?: string;         // Audio format
+
+  // tag info
+  title?: string;          // Track title
+  artist?: string;         // Artist name
+  album?: string;          // Album name
+  year?: number;           // Release year
+  genre?: string;          // Music genre
+  track?: number;          // Track number
+  disc?: number;           // Disc number
+  composer?: string;       // Composer
+  lyricist?: string;       // Lyricist
+  lyrics?: string;         // Lyrics content
+  albumArtist?: string;    // Album artist
+  comment?: string;        // Comment
+}
+```
 
-console.log('Tracks:', customResult.items);
-console.log('Has more:', customResult.hasNextPage);
+#### Example
+
+```js
+import { getTrackMetadataAsync } from '@nodefinity/react-native-music-library';
+
+// Get metadata for a specific track
+const metadata = await getTrackMetadataAsync('track-id-123');
+console.log('Lyrics:', metadata.lyrics);
+console.log('Additional metadata:', metadata.additionalMetadata);
 ```
 
 ## Type Definitions
@@ -125,7 +156,6 @@ interface Track {
   artist?: string;         // Artist name
   artwork?: string;        // Artwork file URI
   album?: string;          // Album name
-  genre?: string;          // Music genre
   lyrics?: string          // Lyrics
   duration: number;        // Duration in seconds
   url: string;             // File URL or path
@@ -158,7 +188,6 @@ type SortByKey =
   | 'duration'
   | 'createdAt'
   | 'modifiedAt'
-  | 'genre'
   | 'trackCount';
 ```
 

README_ZH.md

@@ -74,7 +74,7 @@ iOS 实现尚未完成。现在可以先添加权限到 `Info.plist` 以便将
 在使用此库之前，你需要请求访问音乐库的权限。我们推荐使用以下库之一：
 
 - [react-native-permissions](https://github.com/zoontek/react-native-permissions)
-- [expo-media-library](https://docs.expo.dev/versions/latest/sdk/media-library/)（用于 Expo 项目）
+- [expo-media-library](https://docs.expo.dev/versions/latest/sdk/media-library/)
 
 ## API 参考
 
@@ -95,23 +95,54 @@ iOS 实现尚未完成。现在可以先添加权限到 `Info.plist` 以便将
 - `endCursor`：用于分页的字符串游标
 - `totalCount`：曲目总数（可选）
 
-#### 示例
+### getTrackMetadataAsync(trackId)
 
-```js
-import { getTracksAsync } from '@nodefinity/react-native-music-library';
+获取特定曲目的详细元数据，包括歌词和来自 JAudioTagger 的额外元数据。
 
-// 获取前 20 首曲目（默认）
-const result = await getTracksAsync();
+#### 参数
 
-// 使用自定义选项获取曲目
-const customResult = await getTracksAsync({
-  first: 50,
-  sortBy: ['title', true], // 按标题升序排序
-  directory: '/Music/Favorites'
-});
+- `trackId`：string - 要获取元数据的曲目 ID
+
+#### 返回值
+
+返回一个 Promise，解析为包含以下内容的 `TrackMetadata`：
+
+```typescript
+interface TrackMetadata {
+  id: string;              // 曲目 ID
+
+  // audio header
+  duration?: number;       // 持续时间（秒）
+  bitrate?: number;        // 比特率（kbps）
+  sampleRate?: number;     // 采样率（Hz）
+  channels?: number;       // 通道数
+  format?: string;         // 音频格式
+
+  // tag info
+  title?: string;          // 曲目标题
+  artist?: string;         // 艺术家名称
+  album?: string;          // 专辑名称
+  year?: number;           // 发行年份
+  genre?: string;          // 音乐流派
+  track?: number;          // 曲目编号
+  disc?: number;           // 碟片编号
+  composer?: string;       // 作曲家
+  lyricist?: string;       // 作词家
+  lyrics?: string;         // 歌词内容
+  albumArtist?: string;    // 专辑艺术家
+  comment?: string;        // 注释
+}
+```
 
-console.log('曲目:', customResult.items);
-console.log('是否还有更多:', customResult.hasNextPage);
+#### 示例
+
+```js
+import { getTrackMetadataAsync } from '@nodefinity/react-native-music-library';
+
+// 获取特定曲目的元数据
+const metadata = await getTrackMetadataAsync('track-id-123');
+console.log('歌词:', metadata.lyrics);
+console.log('额外元数据:', metadata.additionalMetadata);
 ```
 
 ## 类型定义
@@ -125,8 +156,6 @@ interface Track {
   artist?: string;         // 艺术家名称
   artwork?: string;        // 专辑封面 URI
   album?: string;          // 专辑名称
-  genre?: string;          // 音乐流派
-  lyrics?: string;         // 歌词
   duration: number;        // 持续时间（秒）
   url: string;             // 文件 URL 或路径
   createdAt?: number;      // 添加日期（Unix 时间戳）
@@ -158,7 +187,6 @@ type SortByKey =
   | 'duration'
   | 'createdAt'
   | 'modifiedAt'
-  | 'genre'
   | 'trackCount';
 ```
 

android/src/main/java/com/musiclibrary/MusicLibraryModule.kt

@@ -3,6 +3,7 @@ package com.musiclibrary
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.Arguments
 import com.facebook.react.module.annotations.ReactModule
 import com.musiclibrary.utils.ReadableMapMapper.toAssetsOptions
 import com.musiclibrary.utils.ModuleUtils.throwUnlessPermissionsGranted
@@ -11,6 +12,7 @@ import com.musiclibrary.tracks.GetTracks
 import com.musiclibrary.albums.GetAlbums
 import com.musiclibrary.artists.GetArtists
 import com.musiclibrary.genres.GetGenres
+import com.musiclibrary.tracks.GetTrackMetadataQuery
 
 @ReactModule(name = MusicLibraryModule.NAME)
 class MusicLibraryModule(reactContext: ReactApplicationContext) :
@@ -56,6 +58,15 @@ class MusicLibraryModule(reactContext: ReactApplicationContext) :
     }
   }
 
+  override fun getTrackMetadataAsync(trackId: String, promise: Promise) {
+    throwUnlessPermissionsGranted(reactApplicationContext, isWrite = false) {
+      withModuleScope(promise) {
+        GetTrackMetadataQuery(reactApplicationContext, trackId, promise)
+          .execute()
+      }
+    }
+  }
+
   companion object {
     const val NAME = "MusicLibrary"
   }

android/src/main/java/com/musiclibrary/models/Assets.kt

@@ -6,15 +6,38 @@ data class Track(
   val artist: String? = null,
   val artwork: String? = null,
   val album: String? = null,
-  val genre: String? = null,
-  val lyrics: String? = null,
   val duration: Double,
   val url: String,
   val createdAt: Long? = null,
   val modifiedAt: Long? = null,
   val fileSize: Long,
 )
 
+data class TrackMetadata(
+  val id: String,
+  
+  // AudioHeader
+  val duration: Double? = null,
+  val bitrate: Long? = null,
+  val sampleRate: Int? = null,
+  val channels: String? = null,
+  val format: String? = null,
+  
+  // Tag
+  val title: String? = null,
+  val artist: String? = null,
+  val album: String? = null,
+  val year: Int? = null,
+  val genre: String? = null,
+  val track: Int? = null,
+  val disc: Int? = null,
+  val composer: String? = null,
+  val lyricist: String? = null,
+  val lyrics: String? = null,
+  val albumArtist: String? = null,
+  val comment: String? = null
+)
+
 data class Album(
   val id: String,
   val title: String,

android/src/main/java/com/musiclibrary/tracks/GetTrackMetadataQuery.kt

@@ -0,0 +1,88 @@
+package com.musiclibrary.tracks
+
+import android.content.Context
+import android.content.ContentResolver
+import android.provider.MediaStore
+import com.facebook.react.bridge.Promise
+import com.musiclibrary.models.TrackMetadata
+import com.musiclibrary.utils.DataConverter
+import java.io.File
+import org.jaudiotagger.audio.AudioFileIO
+import org.jaudiotagger.tag.FieldKey
+
+internal class GetTrackMetadataQuery(
+  private val context: Context,
+  private val trackId: String,
+  private val promise: Promise
+) {
+  fun execute() {
+    try {
+      val contentResolver = context.contentResolver
+      val result = getTrackMetadata(contentResolver, trackId)
+      val writableMap = DataConverter.trackMetadataToWritableMap(result)
+      promise.resolve(writableMap)
+    } catch (e: Exception) {
+      promise.reject("QUERY_ERROR", "Failed to get track metadata: ${e.message}", e)
+    }
+  }
+
+  private fun getTrackMetadata(
+    contentResolver: ContentResolver,
+    trackId: String
+  ): TrackMetadata {
+    // First try to get the file path from MediaStore
+    val projection = arrayOf(MediaStore.Audio.Media.DATA)
+    val selection = "${MediaStore.Audio.Media._ID} = ?"
+    val selectionArgs = arrayOf(trackId)
+
+    val cursor = contentResolver.query(
+      MediaStore.Audio.Media.EXTERNAL_CONTENT_URI,
+      projection,
+      selection,
+      selectionArgs,
+      null
+    )
+
+    cursor?.use { c ->
+      if (c.moveToFirst()) {
+        val dataColumn = c.getColumnIndexOrThrow(MediaStore.Audio.Media.DATA)
+        val filePath = c.getString(dataColumn)
+
+        if (!filePath.isNullOrEmpty()) {
+          try {
+            val audioFile = AudioFileIO.read(File(filePath))
+            val header = audioFile.audioHeader
+            val tag = audioFile.tag
+
+            return TrackMetadata(
+              id = trackId,
+              // AudioHeader
+              duration = header.trackLength.toDouble(),
+              bitrate = header.bitRateAsNumber,
+              sampleRate = header.sampleRateAsNumber,
+              channels = header.channels,
+              format = header.format,
+              // Tag
+              title = tag?.getFirst(FieldKey.TITLE),
+              artist = tag?.getFirst(FieldKey.ARTIST),
+              album = tag?.getFirst(FieldKey.ALBUM),
+              year = tag?.getFirst(FieldKey.YEAR)?.toIntOrNull(),
+              genre = tag?.getFirst(FieldKey.GENRE),
+              track = tag?.getFirst(FieldKey.TRACK)?.toIntOrNull(),
+              disc = tag?.getFirst(FieldKey.DISC_NO)?.toIntOrNull(),
+              composer = tag?.getFirst(FieldKey.COMPOSER),
+              lyricist = tag?.getFirst(FieldKey.LYRICIST),
+              lyrics = tag?.getFirst(FieldKey.LYRICS),
+              albumArtist = tag?.getFirst(FieldKey.ALBUM_ARTIST),
+              comment = tag?.getFirst(FieldKey.COMMENT)
+            )
+          } catch (e: Exception) {
+            // If reading the file fails, return empty metadata
+          }
+        }
+      }
+    }
+
+    return TrackMetadata(id = trackId)
+  }
+}