Adds original audio download feature

We can download recordings from the A2O or from Ecosounds.

Closes #525

docs/.vscode/settings.json

@@ -2,10 +2,17 @@
     "cSpell.words": [
         "Analysing",
         "Ecoacoustics",
+        "Ecosounds",
         "executables",
         "parallelise",
         "recognisers",
         "recognizers",
         "visualise"
-    ]
+    ],
+    "markdownlint.config": {
+        "MD028": false,
+        "MD025": {
+            "front_matter_title": ""
+        }
+    }
 }

docs/technical/commands/download.md

@@ -0,0 +1,34 @@
+---
+title: Download
+uid: command-download
+---
+
+# Download
+
+- **Command**: `download`
+- **Config file**: none (no config file required)
+
+This command shows what sub-commands are available for the `download` command.
+
+## Usage
+
+```shell
+$ AnalysisPrograms.exe download
+```
+
+![download files screenshot](~/images/download.png)
+
+## Options
+
+```shell
+Downloads audio from a repository
+
+
+Commands:
+  batch         Download a multiple files from a remote repository
+  file          Download a single file from a remote repository
+  repositories  Lists available repositories which we can download from
+  search        Preview which files would be downloaded by the batch command
+```
+
+This command has no options. See the sub-commands for more information.

docs/technical/commands/download/batch.md

@@ -0,0 +1,75 @@
+---
+title: Download Batch
+uid: command-download-batch
+---
+
+# Download File
+
+- **Command**: `download file`
+- **Config file**: none (no config file required)
+
+This command downloads one or more files from a remote Acoustic Workbench server.
+You can use the <xref:command-download-search> command to preview which files would be downloaded by the batch command.
+
+
+## Usage
+
+```shell
+$ AnalysisPrograms.exe  download batch [options]
+```
+
+Here is an example of a command line with abbreviated path names:
+
+```shell
+$ AnalysisPrograms.exe  download batch -s 1 -s 2 --start '2021-01-24' --end '2021-12-25' --repository="A2O" --auth-token "REDACTED" --output "D:\Temp\downloads"
+```
+
+![download batch screenshot](~/images/download-batch.png)
+
+This command downloads all the recordings from sites `1` and `2` which were recorded between `2021-01-24` and `2021-12-25`.
+
+You'll need to log in using an authentication token. You can get one by logging in to the website and clicking on the "My Account" link.
+
+## Options
+
+```shell
+Download a single file from a remote repository
+
+Usage: AnalysisPrograms.exe download batch [options] <Ids>
+
+Arguments:
+  Ids                              One or more audio files to download
+
+Options:
+  -p|--project-ids <PROJECT_IDS>   Project IDs to filter recordings by
+  -r|--region-ids <REGION_IDS>     Region IDs to filter recordings by
+  -s|--site-ids <SITE_IDS>         Site IDs to filter recordings by
+  --start <START>                  A date (inclusive) to filter out recordings. Can parse an ISO8601 date.
+  --end <END>                      A date (exclusive) to filter out recordings. Can parse an ISO8601 date.
+  -f|--flat                        If used will not place downloaded files into sub-folders
+  -o|--output <OUTPUT>             A directory to write output to
+  -repo|--repository <REPOSITORY>  Which repository to use to download audio from
+  -a|--auth-token <AUTH_TOKEN>     Your personal access token for the repository
+  ...<global options omitted>...
+```
+
+- `-p|--project-ids <PROJECT_IDS>`: Project IDs to filter recordings by.
+- `-r|--region-ids <REGION_IDS>`: Region IDs to filter recordings by.
+- `-s|--site-ids <SITE_IDS>`: Site IDs to filter recordings by.
+- `--start <START>`: A date (inclusive) to filter out recordings. Can parse an ISO8601 date.
+- `--end <END>`: A date (exclusive) to filter out recordings. Can parse an ISO8601 date.
+- `-f|--flat`: If used will not place downloaded files into sub-folders. Normally recordings are split into sub-folders by their site name.
+- `-o|--output <OUTPUT>`: A directory to put the downloaded audio recordings into.
+- `-repo|--repository <REPOSITORY>`: Which repository to use to download audio from. Either `A2O` or `Ecosounds`
+- `-a|--auth-token <AUTH_TOKEN>`: Your personal access token for the repository.
+
+The options `--repo` and `--auth-token` are required.
+
+You can only choose one of `--project-ids`, `--region-ids`, or `--site-ids` per command.
+But for each you specify the option multiple times. For example, to search multiple sites, you can do this:
+
+```
+... -p 123 -p 456 -p 789 ...
+```
+
+If you specify a start date (`--start`) then you must also include an end date.

docs/technical/commands/download/file.md

@@ -0,0 +1,58 @@
+---
+title: Download File
+uid: command-download-file
+---
+
+# Download File
+
+- **Command**: `download file`
+- **Config file**: none (no config file required)
+
+This command downloads one or more files from a remote Acoustic Workbench server.
+
+The files to download are identified by their unique identifiers.
+You can find the ID for any recording by looking at the URL of the recording,
+or by looking on the details page of a recording.
+
+## Usage
+
+```shell
+$ AnalysisPrograms.exe download [file_ids...] [options]
+```
+
+Here is an example of a command line:
+
+```shell
+$ AnalysisPrograms.exe download file 1 2 3 4 5 7 --repository="A2O" --auth-token "REDACTED" --output "D:\Temp\download"
+```
+
+![download files screenshot](~/images/download-files.png)
+
+This command will download the files with the IDs `1`, `2`, `3`, `4`, `5`, and `7`.
+
+You'll need to log in using an authentication token. You can get one by logging in to the website and clicking on the "My Account" link.
+
+## Options
+
+```shell
+Download a single file from a remote repository
+
+Usage: AnalysisPrograms.exe download file [options] <Ids>
+
+Arguments:
+  Ids                              One or more audio files to download
+
+Options:
+  -f|--flat                        If used will not place downloaded files into sub-folders
+  -o|--output <OUTPUT>             A directory to write output to
+  -repo|--repository <REPOSITORY>  Which repository to use to download audio from
+  -a|--auth-token <AUTH_TOKEN>     Your personal access token for the repository
+  ...<global options omitted>...
+```
+
+- `-f|--flat`: If used will not place downloaded files into sub-folders. Normally recordings are split into sub-folders by their site name.
+- `-o|--output <OUTPUT>`: A directory to put the downloaded audio recordings into.
+- `-repo|--repository <REPOSITORY>`: Which repository to use to download audio from. Either `A2O` or `Ecosounds`
+- `-a|--auth-token <AUTH_TOKEN>`: Your personal access token for the repository.
+
+All options except for `--flat` are required.

docs/technical/commands/download/repositories.md

@@ -0,0 +1,23 @@
+---
+title: Download Repositories
+uid: command-download-repositories
+---
+
+# Download Repositories
+
+- **Command**: `download repositories`
+- **Config file**: none (no config file required)
+
+This list the available repositories which we can download from.
+
+## Usage
+
+```shell
+$ AnalysisPrograms.exe download repositories
+```
+
+![download repositories screenshot](~/images/download-repositories.png)
+
+## Options
+
+This command has not options.

docs/technical/commands/download/search.md

@@ -0,0 +1,68 @@
+---
+title: Download Search
+uid: command-download-search
+---
+
+# Download File
+
+- **Command**: `download search`
+- **Config file**: none (no config file required)
+
+This command searches a repository for recordings.
+
+You can use this command to see which recordings would be downloaded by the <xref:command-download-batch> command.
+
+## Usage
+
+```shell
+$ AnalysisPrograms.exe download search [options]
+```
+
+Here is an example of a command line:
+
+```shell
+$ AnalysisPrograms.exe download search -s 1 -s 2 --start '2021-01-24' --end '2021-12-25' --repository="A2O" --auth-token "REDACTED"
+```
+
+![download search screenshot](~/images/download-search.png)
+
+This command shows all the recordings from sites `1` and `2` which were recorded between `2021-01-24` and `2021-12-25`.
+
+You'll need to log in using an authentication token. You can get one by logging in to the website and clicking on the "My Account" link.
+
+## Options
+
+```shell
+Preview which files would be downloaded by the batch command
+
+Usage: AnalysisPrograms.exe download search [options]
+
+Options:
+  -p|--project-ids <PROJECT_IDS>   Project IDs to filter recordings by
+  -r|--region-ids <REGION_IDS>     Region IDs to filter recordings by
+  -s|--site-ids <SITE_IDS>         Site IDs to filter recordings by
+  --start <START>                  A date (inclusive) to filter out recordings. Can parse an ISO8601 date.
+  --end <END>                      A date (exclusive) to filter out recordings. Can parse an ISO8601 date.
+  -repo|--repository <REPOSITORY>  Which repository to use to download audio from
+  -a|--auth-token <AUTH_TOKEN>     Your personal access token for the repository
+  ...<global options omitted>...
+```
+
+- `-p|--project-ids <PROJECT_IDS>`: Project IDs to filter recordings by.
+- `-r|--region-ids <REGION_IDS>`: Region IDs to filter recordings by.
+- `-s|--site-ids <SITE_IDS>`: Site IDs to filter recordings by.
+- `--start <START>`: A date (inclusive) to filter out recordings. Can parse an ISO8601 date.
+- `--end <END>`: A date (exclusive) to filter out recordings. Can parse an ISO8601 date.
+- `-repo|--repository <REPOSITORY>`: Which repository to use to download audio from. Either `A2O` or `Ecosounds`
+- `-a|--auth-token <AUTH_TOKEN>`: Your personal access token for the repository.
+
+The options `--repo` and `--auth-token` are required.
+
+You can only choose one of `--project-ids`, `--region-ids`, or `--site-ids` per command.
+But for each you specify the option multiple times. For example, to search multiple sites, you can do this:
+
+```
+... -p 123 -p 456 -p 789 ...
+```
+
+If you specify a start date (`--start`) then you must also include an end date.

docs/technical/commands/toc.yml

@@ -6,3 +6,14 @@
   href: draw_false_colour_spectrogram.md
 - name: Concatenate Index Files
   href: concatenate_index_files.md
+- name: Download
+  href: download.md
+  items:
+    - name: Repositories
+      href: download/repositories.md
+    - name: File
+      href: download/file.md
+    - name: Search
+      href: download/search.md
+    - name: Batch
+      href: download/batch.md

src/AcousticWorkbench/AcousticWorkbench.csproj

@@ -10,4 +10,8 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Acoustics.Shared\Acoustics.Shared.csproj" />
+  </ItemGroup>
 </Project>

src/AcousticWorkbench/AcousticWorkbenchListResponse.cs

@@ -0,0 +1,12 @@
+// <copyright file="AcousticWorkbenchListResponse.cs" company="QutEcoacoustics">
+// All code in this file and all associated files are the copyright and property of the QUT Ecoacoustics Research Group (formerly MQUTeR, and formerly QUT Bioacoustics Research Group).
+// </copyright>
+
+namespace AcousticWorkbench
+{
+    public class AcousticWorkbenchListResponse<T>
+        : AcousticWorkbenchResponse<T>
+    {
+        public T[] Data { get; set; }
+    }
+}

src/AcousticWorkbench/AcousticWorkbenchResponse{T}.cs

@@ -4,49 +4,9 @@
 
 namespace AcousticWorkbench
 {
-    using System;
-    using System.Collections.Generic;
-    using Newtonsoft.Json;
-    using Newtonsoft.Json.Linq;
 
-    //    [JsonObject(NamingStrategyType = typeof(SnakeCaseNamingStrategy))]
-    //    public abstract class RubyJsonObject
-    //    {
-    //    }
-
-    public class AcousticWorkbenchResponse<T>
+    public abstract class AcousticWorkbenchResponse<T>
     {
         public Meta Meta { get; set; }
-
-        public T Data { get; set; }
-    }
-
-    public class Meta
-    {
-        public string Status { get; set; }
-
-        public string Message { get; set; }
-
-        public Error Error { get; set; }
-
-        public override string ToString()
-        {
-            return $"[Status: {this.Status}] {this.Message}\n" +
-                (this.Error?.ToString() ?? string.Empty);
-        }
-    }
-
-    public class Error
-    {
-        public string Details { get; set; }
-
-        public Dictionary<string, string> Links { get; set; }
-
-        public JRaw Info { get; set; }
-
-        public override string ToString()
-        {
-            return "API error: " + this.Details + Environment.NewLine + (this.Info.ToString(Formatting.Indented) ?? string.Empty);
-        }
     }
 }