{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%cd ..\n",
    "import sys\n",
    "\n",
    "sys.path.append(\"/workspaces/waloviz/src\")\n",
    "sys.path.append(\"/home/runner/work/waloviz/waloviz/src\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The `Audio` function\n",
    "The most important function in WaloViz and the reason for it to exist.  \n",
    "When you need the WaloViz player in a jupyter notebook, use the `Audio` function.  \n",
    "\n",
    "The most simple way to call `Audio` is like so:  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import waloviz as wv\n",
    "\n",
    "wv.extension()\n",
    "wv.Audio(\"https://www2.cs.uic.edu/~i101/SoundFiles/CantinaBand3.wav\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> Notice that we've called the `extension` function, like the `import` it should be called once per notebook.  \n",
    "\n",
    "As you can see, the player has all sorts of features, if the default settings are more\\less than you need, you can set the `minimal` flag for less features or the `extended` flag for more features:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "\n",
    "pn.Row(\n",
    "    wv.Audio(\n",
    "        \"https://www2.cs.uic.edu/~i101/SoundFiles/CantinaBand3.wav\",\n",
    "        minimal=True,\n",
    "        title=\"minimal\",\n",
    "    ),\n",
    "    wv.Audio(\n",
    "        \"https://www2.cs.uic.edu/~i101/SoundFiles/CantinaBand3.wav\",\n",
    "        extended=True,\n",
    "        title=\"extended\",\n",
    "    ),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> This time we displayed two players side by side, to do so we used the `panel` library, which WaloViz is based on.  \n",
    "> For more information, read the [`panel` docs](https://panel.holoviz.org/).\n",
    "\n",
    "You can call the `Audio` function with any audio file URL or path:\n",
    "```python\n",
    "# URL\n",
    "wv.Audio('https://www2.cs.uic.edu/~i101/SoundFiles/CantinaBand3.wav')\n",
    "# Local path\n",
    "wv.Audio('local_data/CantinaBand3.wav')\n",
    "# File-like-obj\n",
    "with open('local_data/CantinaBand3.wav') as f:\n",
    "    wv.Audio(f)\n",
    "# All of the above will produce the same player\n",
    "```\n",
    "\n",
    "Or, if you're processing your audio as an array or tensor, just specify the sample-rate and it'll work:  \n",
    "```python\n",
    "# A tensor \n",
    "import torchaudio\n",
    "wav, sr = torchaudio.load('local_data/CantinaBand3.wav')\n",
    "wv.Audio((wav, sr))\n",
    "wv.Audio(wav, sr=sr)\n",
    "# Or a numpy array\n",
    "np_wav = wav.numpy()\n",
    "wv.Audio((np_wav, sr))\n",
    "# All of the above will produce the same player\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The `save` function\n",
    "When you want to capture a WaloViz player in an HTML file, just replace the `Audio` function with the `save` function:\n",
    "```python\n",
    "# Local path\n",
    "wv.save('local_data/CantinaBand3.wav', extended=True)\n",
    "# A tensor\n",
    "wav, sr = torchaudio.load('local_data/CantinaBand3.wav')\n",
    "wv.save((wav, sr))\n",
    "wv.save(wav, sr=sr)\n",
    "# All of the above will produce the same HTML\n",
    "```\n",
    "\n",
    "The default output file path is `waloviz.html`, you can specify your own path like so:  \n",
    "```python\n",
    "wv.save('local_data/CantinaBand3.wav', 'your/own/path.html')\n",
    "wv.save('local_data/CantinaBand3.wav', out_file='your/own/path.html')\n",
    "# All of the above will produce the same HTML\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}