Metadata-Version: 2.1
Name: inspec
Version: 0.3
Summary: Printing and viewing spectrograms of audio files in command line
Home-page: https://github.com/kevinyu/inspec
Author: Kevin Yu
Author-email: thekevinyu@gmail.edu
License: MIT
Keywords: spectrogram audio visualization sound terminal
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: Click
Requires-Dist: SoundFile
Requires-Dist: numpy
Requires-Dist: Pillow
Requires-Dist: sounddevice
Requires-Dist: wheel
Requires-Dist: windows-curses ; platform_system == "Windows"

# inspec

Inspect audio files and images from the command line by displaying them as unicode characters.

Primary purpose is to inspect media files on a server during a remote SSH session or to quickly spot-check files during a script. Provides printing to stdout, a terminal gui built with curses, and importable Python functions.

## Install

```
pip install inspec
```

## Usage

### Command Line

Launch the GUI viewer for audio files and image files respectively. At some point I probably want to merge these two commands and infer the file type from the extensions.
```shell
inspec open FILENAME [-r ROWS] [-c COLS] [--cmap CMAP]
inspec imopen FILENAME [-r ROWS] [-c COLS] [--cmap CMAP]
```

Print a file to stdout, inferring type of file base on extension and contents (audio and image versions)
```shell
inspec show FILENAME [-w WIDTH] [-h HEIGHT] [--cmap CMAP] [--horizontal OR --vertical]
inspec imshow FILENAME [-w WIDTH] [-h HEIGHT] [--cmap CMAP] [--horizontal OR --vertical]
```

Show a live spectrogram or amplitude of an input device
```shell
inspec listen [-d DEVICE] [-c CHANNELS] [-m 'spec' OR 'amp'] [--cmap CMAP]
```

```shell
inspec list-devices
inspec list-cmaps
```

### Python

Convenience methods mirroring the cli

```python
import inspec

# Open a terminal gui
inspec.open_gui(FILENAMES, rows=2, cols=2, cmap="viridis")
inspec.open_image_gui(FILENAMES, rows=4, cols=3, cmap="greys")

# Printing to stdout
inspec.show(FILENAME, width=0.5, height=0.5)
inspec.imshow(FILENAME, width=0.5, height=0.5)

# Open a gui displaying live spectrograms
inspec.listen(device=DEVICE, channels=1)
```

### 'inspec open' and 'inspec imopen' commands

**General controls**

| Action                             |Key|
|---|---|
|  Close the program                 |[q]|
|  Change selected file              |[arrow keys] or [h,j,k,l] |
|  Prompt to set display rows        |[r]|
|  Prompt to set display cols (int)  |[c]|
|  Prompt to jump to page (int)      |[p]|

**Audio only**

| Action                             |Key|
|---|---|
|  Zoom out/in in time               |[+]| and [-]|
|  Prompt to set timescale (float)   |[s]|
|  Toggle spectrogram/amplitude view |[z]|
|  Scroll file in time                    |[shift + arrow keys] or [H,L]|
|  Prompt to jump to time (seconds)  |[t]|
|  Switch to channel (0 indexed, max 9) |[number keys]|

**Images only**

| Action                             |Key|
|---|---|
|  Toggle thumbnail (lower resolution) |[z]|

### 'inspec listen' commands

| Action                             |Key|
|---|---|
|  Close the program                 |[q]|
|  Increase gain                     |[up arrow] or [k] |
|  Decrease gain                     |[down arrow] or [j]|
|  Zoom in on y scale                |[+]|
|  Zoom out on y scale               |[-]|
|  Prompt to set gain (float in dB, defaults 0) |[g]|

#### Rendering data

For more fine-grained control, or to extend the visualizations to other data formats, you can add/modify/remove intermediate processing steps. These are

1. reading in data (`inspec.io`)

2. converting to 2D image array (`inspec.transform`)

3. converting image data into 2d array of unicode characters and foreground/background scale values between 0 and 1 (`inspec.maps`)

4. applying a colormap to the colors, converting into a 2d array of unicode characters and foreground/background color values (`StdoutRenderer.apply_colormap_to_char_array()`)

3. and then displaying those characters. (`StdoutRenderer.render()`)

```python
import inspec
from inspec.colormap import load_cmap
from inspec.io import AudioReader
from inspec.maps import QuarterCharMap
from inspec.render import StdoutRenderer
from inspec.transform import SpectrogramTransform

cmap = load_cmap("viridis")
transform = SpectrogramTransform(1000, 50, min_freq=250, max_freq=10000)

data, sampling_rate, _ = AudioReader.read_file("sample.wav")

# Convert the data into a 2D image
img, _ = transform.convert(data, sampling_rate, output_size=(80, 160))

# Convert the image into tuples of unicode characters and colors to map (from 0. to 1.)
char_img = QuarterCharMap.to_char_array(img)

# Apply a colormap to the 0. to 1. colors into terminal color values (or curses colors)
char_img_colorized = StdoutRenderer.apply_cmap_to_char_array(cmap, char_img)

# Display the characters and colors to the screen
StdoutRenderer.display(char_img_colorized)
```

## Compatibility

Definitely works on Ubuntu + Python3.8. Kind of works on Windows 10 + Python3.8 in Powershell but a little unstable, needs `pip install windows-curses` as well.


