update documentation

README.md

@@ -9,7 +9,18 @@ tags:
 # Descript Audio Codec (DAC)
 DAC is the state-of-the-art audio tokenizer with improvement upon the previous tokenizers like SoundStream and EnCodec.
 
-This model card provides an easy-to-use API for a *pretrained DAC* [1] whose backbone and pretrained weights are from [its original reposotiry](https://github.com/descriptinc/descript-audio-codec). With this API, you can encode and decode by a single line of code either using CPU or GPU. Furhtermore, it supports chunk-based processing for memory-efficient processing, especially important for GPU processing. 
+This model card provides an easy-to-use API for a *pretrained DAC* [1] for 44.1khz audio whose backbone and pretrained weights are from [its original reposotiry](https://github.com/descriptinc/descript-audio-codec). With this API, you can encode and decode by a single line of code either using CPU or GPU. Furhtermore, it supports chunk-based processing for memory-efficient processing, especially important for GPU processing. 
+
+
+### Model variations
+There are three types of model depending on an input audio sampling rate. 
+
+| Model | Input audio sampling rate [khz] |
+| ------------------ | ----------------- |
+| [`hance-ai/descript-audio-codec-44khz`](https://huggingface.co/hance-ai/descript-audio-codec-24khz) | 44.1khz |
+| [`hance-ai/descript-audio-codec-24khz`](https://huggingface.co/hance-ai/descript-audio-codec-24khz) | 24khz |
+| [`hance-ai/descript-audio-codec-16khz`](https://huggingface.co/hance-ai/descript-audio-codec-16khz) | 16khz |
+
 
 
 # Usage
@@ -17,14 +28,42 @@ This model card provides an easy-to-use API for a *pretrained DAC* [1] whose bac
 ### Load
 ```python
 from transformers import AutoModel
+
+# device setting
+device = 'cpu'  # or 'cuda:0'
+
+# load
 model = AutoModel.from_pretrained('hance-ai/descript-audio-codec', trust_remote_code=True)
+model.to(device)
 ```
 
+### Encode
+```python
+audio_filename = ...
+zq, s = model.encode(audio_filename)
+```
+`zq` is discrete embeddings with dimension of (1, num_RVQ_codebooks, token_length) and `s` is a token sequence with dimension of (1, num_RVQ_codebooks, token_length). 
 
-<!-- 
-- different models for different khz  
-- how to adjust model parameters
--->
+
+### Decode
+```python
+# decoding from `zq`
+waveform = model.decode(zq=zq)  # (1, 1, audio_length); the output has a mono channel.
+
+# decoding from `s`
+waveform = model.decode(s=s)  # (1, 1, audio_length); the output has a mono channel.
+```
+
+### Save a waveform as an audio file.
+```python
+model.waveform_to_audiofile(waveform, 'out.wav')
+```
+
+### Save and load tokens
+```python
+model.save_tensor(s, 'tokens.pt')
+loaded_s = model.load_tensor('tokens.pt')
+```
 
 
 # Runtime

save_model.ipynb

@@ -101,302 +101,33 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [
     {
-     "data": {
-      "text/plain": [
-       "DAC(\n",
-       "  (dac): DAC(\n",
-       "    (encoder): Encoder(\n",
-       "      (block): Sequential(\n",
-       "        (0): Conv1d(1, 64, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "        (1): EncoderBlock(\n",
-       "          (block): Sequential(\n",
-       "            (0): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(64, 64, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(64, 64, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (1): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(64, 64, kernel_size=(7,), stride=(1,), padding=(9,), dilation=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(64, 64, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (2): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(64, 64, kernel_size=(7,), stride=(1,), padding=(27,), dilation=(9,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(64, 64, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (3): Snake1d()\n",
-       "            (4): Conv1d(64, 128, kernel_size=(4,), stride=(2,), padding=(1,))\n",
-       "          )\n",
-       "        )\n",
-       "        (2): EncoderBlock(\n",
-       "          (block): Sequential(\n",
-       "            (0): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(128, 128, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(128, 128, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (1): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(128, 128, kernel_size=(7,), stride=(1,), padding=(9,), dilation=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(128, 128, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (2): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(128, 128, kernel_size=(7,), stride=(1,), padding=(27,), dilation=(9,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(128, 128, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (3): Snake1d()\n",
-       "            (4): Conv1d(128, 256, kernel_size=(8,), stride=(4,), padding=(2,))\n",
-       "          )\n",
-       "        )\n",
-       "        (3): EncoderBlock(\n",
-       "          (block): Sequential(\n",
-       "            (0): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(256, 256, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(256, 256, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (1): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(256, 256, kernel_size=(7,), stride=(1,), padding=(9,), dilation=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(256, 256, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (2): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(256, 256, kernel_size=(7,), stride=(1,), padding=(27,), dilation=(9,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(256, 256, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (3): Snake1d()\n",
-       "            (4): Conv1d(256, 512, kernel_size=(16,), stride=(8,), padding=(4,))\n",
-       "          )\n",
-       "        )\n",
-       "        (4): EncoderBlock(\n",
-       "          (block): Sequential(\n",
-       "            (0): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(512, 512, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(512, 512, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (1): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(512, 512, kernel_size=(7,), stride=(1,), padding=(9,), dilation=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(512, 512, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (2): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(512, 512, kernel_size=(7,), stride=(1,), padding=(27,), dilation=(9,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(512, 512, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (3): Snake1d()\n",
-       "            (4): Conv1d(512, 1024, kernel_size=(16,), stride=(8,), padding=(4,))\n",
-       "          )\n",
-       "        )\n",
-       "        (5): Snake1d()\n",
-       "        (6): Conv1d(1024, 1024, kernel_size=(3,), stride=(1,), padding=(1,))\n",
-       "      )\n",
-       "    )\n",
-       "    (quantizer): ResidualVectorQuantize(\n",
-       "      (quantizers): ModuleList(\n",
-       "        (0-8): 9 x VectorQuantize(\n",
-       "          (in_proj): Conv1d(1024, 8, kernel_size=(1,), stride=(1,))\n",
-       "          (out_proj): Conv1d(8, 1024, kernel_size=(1,), stride=(1,))\n",
-       "          (codebook): Embedding(1024, 8)\n",
-       "        )\n",
-       "      )\n",
-       "    )\n",
-       "    (decoder): Decoder(\n",
-       "      (model): Sequential(\n",
-       "        (0): Conv1d(1024, 1536, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "        (1): DecoderBlock(\n",
-       "          (block): Sequential(\n",
-       "            (0): Snake1d()\n",
-       "            (1): ConvTranspose1d(1536, 768, kernel_size=(16,), stride=(8,), padding=(4,))\n",
-       "            (2): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(768, 768, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(768, 768, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (3): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(768, 768, kernel_size=(7,), stride=(1,), padding=(9,), dilation=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(768, 768, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (4): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(768, 768, kernel_size=(7,), stride=(1,), padding=(27,), dilation=(9,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(768, 768, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "          )\n",
-       "        )\n",
-       "        (2): DecoderBlock(\n",
-       "          (block): Sequential(\n",
-       "            (0): Snake1d()\n",
-       "            (1): ConvTranspose1d(768, 384, kernel_size=(16,), stride=(8,), padding=(4,))\n",
-       "            (2): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(384, 384, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(384, 384, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (3): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(384, 384, kernel_size=(7,), stride=(1,), padding=(9,), dilation=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(384, 384, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (4): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(384, 384, kernel_size=(7,), stride=(1,), padding=(27,), dilation=(9,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(384, 384, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "          )\n",
-       "        )\n",
-       "        (3): DecoderBlock(\n",
-       "          (block): Sequential(\n",
-       "            (0): Snake1d()\n",
-       "            (1): ConvTranspose1d(384, 192, kernel_size=(8,), stride=(4,), padding=(2,))\n",
-       "            (2): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(192, 192, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(192, 192, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (3): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(192, 192, kernel_size=(7,), stride=(1,), padding=(9,), dilation=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(192, 192, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (4): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(192, 192, kernel_size=(7,), stride=(1,), padding=(27,), dilation=(9,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(192, 192, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "          )\n",
-       "        )\n",
-       "        (4): DecoderBlock(\n",
-       "          (block): Sequential(\n",
-       "            (0): Snake1d()\n",
-       "            (1): ConvTranspose1d(192, 96, kernel_size=(4,), stride=(2,), padding=(1,))\n",
-       "            (2): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(96, 96, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(96, 96, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (3): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(96, 96, kernel_size=(7,), stride=(1,), padding=(9,), dilation=(3,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(96, 96, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "            (4): ResidualUnit(\n",
-       "              (block): Sequential(\n",
-       "                (0): Snake1d()\n",
-       "                (1): Conv1d(96, 96, kernel_size=(7,), stride=(1,), padding=(27,), dilation=(9,))\n",
-       "                (2): Snake1d()\n",
-       "                (3): Conv1d(96, 96, kernel_size=(1,), stride=(1,))\n",
-       "              )\n",
-       "            )\n",
-       "          )\n",
-       "        )\n",
-       "        (5): Snake1d()\n",
-       "        (6): Conv1d(96, 1, kernel_size=(7,), stride=(1,), padding=(3,))\n",
-       "        (7): Tanh()\n",
-       "      )\n",
-       "    )\n",
-       "  )\n",
-       ")"
-      ]
-     },
-     "execution_count": 7,
-     "metadata": {},
-     "output_type": "execute_result"
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "C:\\Users\\dslee\\AppData\\Roaming\\Python\\Python38\\site-packages\\tqdm\\auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
+      "  from .autonotebook import tqdm as notebook_tqdm\n",
+      "c:\\Users\\dslee\\anaconda3\\envs\\sound_effect_variation_generation\\lib\\site-packages\\huggingface_hub\\file_download.py:159: UserWarning: `huggingface_hub` cache-system uses symlinks by default to efficiently store duplicated files but your machine does not support them in C:\\Users\\dslee\\.cache\\huggingface\\hub\\models--hance-ai--descript-audio-codec-44khz. Caching files will still work but in a degraded version that might require more space on your disk. This warning can be disabled by setting the `HF_HUB_DISABLE_SYMLINKS_WARNING` environment variable. For more details, see https://huggingface.co/docs/huggingface_hub/how-to-cache#limitations.\n",
+      "To support symlinks on Windows, you either need to activate Developer Mode or to run Python as an administrator. In order to see activate developer mode, see this article: https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development\n",
+      "  warnings.warn(message)\n",
+      "A new version of the following files was downloaded from https://huggingface.co/hance-ai/descript-audio-codec-44khz:\n",
+      "- model.py\n",
+      ". Make sure to double-check they do not contain any added malicious code. To avoid downloading new versions of the code file, you can pin a revision.\n",
+      "C:\\Users\\dslee\\AppData\\Roaming\\Python\\Python38\\site-packages\\audiotools\\ml\\layers\\base.py:172: FutureWarning: You are using `torch.load` with `weights_only=False` (the current default value), which uses the default pickle module implicitly. It is possible to construct malicious pickle data which will execute arbitrary code during unpickling (See https://github.com/pytorch/pytorch/blob/main/SECURITY.md#untrusted-models for more details). In a future release, the default value for `weights_only` will be flipped to `True`. This limits the functions that could be executed during unpickling. Arbitrary objects will no longer be allowed to be loaded via this mode unless they are explicitly allowlisted by the user via `torch.serialization.add_safe_globals`. We recommend you start setting `weights_only=True` for any use case where you don't have full control of the loaded file. Please open an issue on GitHub for any issues related to this experimental feature.\n",
+      "  model_dict = torch.load(location, \"cpu\")\n",
+      "c:\\Users\\dslee\\anaconda3\\envs\\sound_effect_variation_generation\\lib\\site-packages\\torch\\nn\\utils\\weight_norm.py:134: FutureWarning: `torch.nn.utils.weight_norm` is deprecated in favor of `torch.nn.utils.parametrizations.weight_norm`.\n",
+      "  WeightNorm.apply(module, name, dim)\n"
+     ]
     }
    ],
    "source": [
     "# load the uploaded model\n",
     "from transformers import AutoModel\n",
-    "model = AutoModel.from_pretrained('hance-ai/descript-audio-codec', \n",
-    "                                  trust_remote_code=True)\n",
-    "model.to('cpu')"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "model."
+    "model = AutoModel.from_pretrained('hance-ai/descript-audio-codec-44khz', trust_remote_code=True)\n",
+    "model.to('cpu');"
    ]
   },
   {

test_DAC.ipynb

@@ -50,7 +50,7 @@
    "source": [
     "# load the model\n",
     "config = DACConfig(model_type_by_sampling_freq=model_type_by_sampling_freq)\n",
-    "dac = DAC(config).to(device)"
+    "model = DAC(config).to(device)"
    ]
   },
   {
@@ -69,7 +69,7 @@
    ],
    "source": [
     "# encoding\n",
-    "zq, s = dac.encode(fname)\n",
+    "zq, s = model.encode(fname)\n",
     "print('zq.shape:', zq.shape)\n",
     "print('s.shape:', s.shape)"
    ]
@@ -97,7 +97,7 @@
    ],
    "source": [
     "# decoding (from zq -- discrete latent vectors)\n",
-    "waveform = dac.decode(zq=zq)\n",
+    "waveform = model.decode(zq=zq)\n",
     "print('waveform.shape:', waveform.shape)"
    ]
   },
@@ -116,7 +116,7 @@
    ],
    "source": [
     "# decoding (from s -- tokens)\n",
-    "waveform = dac.decode(s=s)\n",
+    "waveform = model.decode(s=s)\n",
     "print('waveform.shape:', waveform.shape)"
    ]
   },
@@ -127,7 +127,7 @@
    "outputs": [],
    "source": [
     "# save waveform into an audio file\n",
-    "dac.waveform_to_audiofile(waveform, 'out.wav')"
+    "model.waveform_to_audiofile(waveform, 'out.wav')"
    ]
   },
   {
@@ -146,8 +146,8 @@
    ],
    "source": [
     "# save and load tokens\n",
-    "dac.save_tensor(s, 'tokens.pt')\n",
-    "loaded_s = dac.load_tensor('tokens.pt')  # s == loaded_s"
+    "model.save_tensor(s, 'tokens.pt')\n",
+    "loaded_s = model.load_tensor('tokens.pt')  # s == loaded_s"
    ]
   },
   {