feat(file-engine): extract audio file metadata for track information

docs/api/core.md

@@ -571,7 +571,7 @@ Player engines are the heart of `discord-player-plus`. They are responsible for
     source: string;
     /**
      * Whether this engine is responsible for searching/streaming the given query.
-     * If not available engines are responsible for a user query, YouTube will be automatically selected.
+     * If no available engines are responsible for a user query, YouTube will be used.
      */
     isResponsible(
       query: string,
@@ -704,7 +704,7 @@ interface Track {
   duration: number;
   artist?: string;
   /**
-   * Track source (used player engine)
+   * Track source (used player engine). Built-in engines/sources: `youtube`, `spotify`, `file`.
    *
    * @example "youtube"
    */

docs/guide/engines.md

@@ -1,12 +1,10 @@
-# Player engines
+---
+outline: deep
+---
 
-Player engines are the heart of `discord-player-plus`. They are responsible for searching tracks and streaming them using different streaming providers such as YouTube or Spotify. Following player engines are built-in:
+# Player engines
 
-- YouTube
-- Spotify
-  - **YouTube mapping:** Spotify does not provide a web API to stream tracks so they are only searched on Spotify but streamed on YouTube
-  - **Limitations:** Tracks can only be searched by URL, not by title. Also when searching playlists, only the first 100 tracks will be searched
-- Files (local files on your file system, e.g. `my-music.mp3`)
+Player engines are the heart of `discord-player-plus`. They are responsible for searching tracks and streaming them using different streaming providers such as YouTube or Spotify.
 
 When you use `player.search()` the engine will be detected automatically but you can also specify which engine you want to use with:
 
@@ -18,11 +16,30 @@ const searchResults = await player.search("my song to search", {
 
 If no engine is found for your search, YouTube will be used as fallback.
 
-## Local files
+## Built-in engines
+
+Following player engines are provided by `discord-player-plus` out-of-the-box:
+
+### YouTube
+
+- Default engine
+- Search and play tracks and playlists by url or title
+- Supports YouTube Music.
 
-You can also play local files from your filesystem by setting the file path as the track url or search query. The pre-build `/play` and `/add` command allow you to search local songs by using the file path as query.
+### Spotify
 
-### Set file root
+- Search tracks and playlists by url
+- **YouTube mapping:** Spotify does not provide a web API to stream tracks so they are only searched on Spotify but streamed on YouTube
+- **Limitations:** Tracks can only be searched by URL, not by title. Also when searching playlists, only the first 100 tracks will be searched
+
+### Local files
+
+- Search and play local files by file path on your file system, e.g. `./files/my-music.mp3`
+- Supports file metadata (will extract e.g. title and artists from the file if available)
+
+The pre-build `/play` and `/add` command allow you to search local songs by using the file path as query. You can also create your track object manually and set the file path as `url` and set the `source` property to `file`.
+
+#### Set file root
 
 ::: warning
 For security reasons you have to set `fileRoot` of the player options. Only local files inside this folder are allowed to play. In the following example only files inside `../path/to/my/folder` will be playable.
@@ -39,52 +56,9 @@ const playerManager = new PlayerManager({
 });
 ```
 
-### Play file
-
-- Using `player.search()`:
-
-  ```ts
-  // get voice channel from e.g. slash command interaction
-  const voiceChannel;
-
-  const searchResults = await player.search(
-    path.join(__dirname, "../path/to/my/folder/example.mp3")
-  );
-
-  if (searchResults.length && searchResults[0].tracks.length) {
-    await player.play({
-      channel: voiceChannel,
-      tracks: searchResults[0].tracks.slice(1),
-    });
-  }
-  ```
-
-- Using manually created track:
-
-  You need to set `source` to `file` and the file path as `url`.
-
-  ```ts
-  import { Track } from "discord-player-plus";
-
-  // get voice channel from e.g. slash command interaction
-  const voiceChannel;
-
-  const track: Track = {
-    title: "My local file",
-    url: path.join(__dirname, "../path/to/my/folder/example.mp3"),
-    duration: 30,
-    source: "file",
-  };
-
-  await player.play({
-    channel: voiceChannel,
-    tracks: [track],
-  });
-  ```
-
 ## Custom engines
 
-You can use custom engines to override existing ones or add additional streaming providers. Custom player engines have higher priority than build-in ones so if you add a custom engine that is responsible for tracks that a build-in engine is responsible for, your engine will be used instead.
+You can use custom engines to override existing ones or add additional streaming providers. Custom player engines have higher priority than built-in ones so if you add a custom engine that is responsible for tracks that a built-in engine is responsible for, your engine will be used instead.
 
 ::: info
 If you are planning to add a player engine for a new streaming provider, please feel free to contribute to `discord-player-plus` by [creating a pull request](https://github.com/larsrickert/discord-player-plus/pulls) that adds the engine to the library so others can use it too.

docs/index.md

@@ -23,10 +23,10 @@ features:
     details: Clean and intuitive API for easily playing music and sounds. No additional dependencies needed.
   - icon: 🎶
     title: Multiple Guilds
-    details: Support for multiple guilds/discord servers out-of-the-box. Individual players will automatically be managed for you.
+    details: Supports multiple discord servers (guilds) out-of-the-box. Individual players will automatically be managed for you.
   - icon: 💿
     title: Multiple sources
-    details: Play from YouTube, Spotify, local files or custom sources using the player engine API.
+    details: Play from YouTube/YouTube Music, Spotify, local files or custom sources using the player engine API.
   - icon: 🚀
     title: Pre-build Slash Commands
     details: Customizable pre-build slash commands for all core functionalities. Get you music bot up and running in a few minutes.