Skip to content

Commit a55d9a6

Browse files
CyanVoxelCyanVoxel
committed
docs: add preview support section to library page
1 parent 2c5c98c commit a55d9a6

File tree

3 files changed

+176
-2
lines changed

3 files changed

+176
-2
lines changed

‎docs/library/index.md‎

Lines changed: 152 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,155 @@
1-
# Library
1+
# :material-database: Library
2+
3+
<!-- prettier-ignore -->
4+
!!! info
5+
This page is a work in progress and needs to be updated with additional information.
26

37
The library is how TagStudio represents your chosen directory, with every file inside being represented by a [file entry](./entry.md). You can have as many or few libraries as you wish, since each libraries' data is stored within a `.TagStudio` folder at its root. From there the library save file itself is stored as `ts_library.sqlite`, with TagStudio versions 9.4 and below using a the legacy `ts_library.json` format.
48

5-
Note that this means [tags](./tag.md) you create only exist _per-library_.
9+
Note that this means [tags](./tag.md) you create only exist _per-library_. Global tags along with other library structure updates are planned for future releases on the [roadmap](../updates/roadmap.md#library).
10+
11+
---
12+
13+
## Preview Support
14+
15+
TagStudio offers built-in preview and thumbnail support for a wide variety of file types. Files that don't have explicit support can still be added to your library like normal, they will just show a default icon for thumbnails and previews. TagStudio also references the file's [MIME](https://en.wikipedia.org/wiki/Media_type) type in an attempt to render previews for file types that haven't gained explicit support yet.
16+
17+
### :material-image-outline: Images
18+
19+
Images will generate thumbnails the first time they are viewed or since the last time they were modified. Thumbnails are used in the grid view, but not in the Preview Panel. Animated images will play in the Preview Panel.
20+
21+
| Filetype | Extensions | Animation |
22+
| -------------------- | -------------------------------------------------- | :---------------------------------: |
23+
| Animated PNG | `.apng` | :material-check-circle:{.lg .green} |
24+
| Apple Icon Image | `.icns` | :material-minus-circle:{.lg .gray} |
25+
| AVIF | `.avif` | :material-minus-circle:{.lg .gray} |
26+
| Bitmap | `.bmp` | :material-minus-circle:{.lg .gray} |
27+
| GIF | `.gif` | :material-check-circle:{.lg .green} |
28+
| HEIF | `.heif`, `.heic` | :material-minus-circle:{.lg .gray} |
29+
| JPEG | `.jpeg`, `.jpg`, `.jfif`, `.jif`, `.jpg_large`[^1] | :material-minus-circle:{.lg .gray} |
30+
| JPEG-XL | `.jxl` | :material-close-circle:{.lg .red} |
31+
| OpenEXR | `.exr` | :material-minus-circle:{.lg .gray} |
32+
| OpenRaster | `.ora` | :material-minus-circle:{.lg .gray} |
33+
| PNG | `.png` | :material-minus-circle:{.lg .gray} |
34+
| SVG | `.svg` | :material-minus-circle:{.lg .gray} |
35+
| TIFF | `.tiff`, `.tif` | :material-minus-circle:{.lg .gray} |
36+
| Valve Texture Format | `.vtf` | :material-close-circle:{.lg .red} |
37+
| WebP | `.webp` | :material-check-circle:{.lg .green} |
38+
| Windows Icon | `.ico` | :material-minus-circle:{.lg .gray} |
39+
40+
#### :material-image-outline: RAW Images
41+
42+
| Filetype | Extensions |
43+
| -------------------------------- | ---------------------- |
44+
| Camera Image File Format (Canon) | `.crw`, `.cr2`, `.cr3` |
45+
| Digital Negative | `.dng` |
46+
| Fuji RAW | `.raf` |
47+
| Nikon RAW | `.nef`, `.nrw` |
48+
| Olympus RAW | `.orf` |
49+
| Panasonic RAW | `.raw`, `.rw2` |
50+
| Sony RAW | `.arw` |
51+
52+
### :material-movie-open: Videos
53+
54+
Video thumbnails will default to the closest viable frame from the middle of the video. Both thumbnail generation and video playback in the Preview Panel requires [FFmpeg](../install.md#third-party-dependencies) installed on your system.
55+
56+
| Filetype | Extensions | Dependencies |
57+
| --------------------- | ----------------------- | :----------: |
58+
| 3GP | `.3gp` | FFmpeg |
59+
| AVI | `.avi` | FFmpeg |
60+
| AVIF | `.avif` | FFmpeg |
61+
| FLV | `.flv` | FFmpeg |
62+
| HEVC | `.hevc` | FFmpeg |
63+
| Matroska | `.mkv` | FFmpeg |
64+
| MP4 | `.mp4` , `.m4p` | FFmpeg |
65+
| MPEG Transport Stream | `.ts` | FFmpeg |
66+
| QuickTime | `.mov`, `.movie`, `.qt` | FFmpeg |
67+
| WebM | `.webm` | FFmpeg |
68+
| WMV | `.wmv` | FFmpeg |
69+
70+
### :material-sine-wave: Audio
71+
72+
Audio thumbnails will default to embedded cover art (if any) andfallback to generated waveform thumbnails. Audio file playback is supported in the Preview Panel if you have [FFmpeg](../install.md#third-party-dependencies) installed on your system. Audio waveforms are currently not cached.
73+
74+
| Filetype | Extensions | Dependencies |
75+
| ------------------- | ------------------------ | :----------: |
76+
| AAC | `.aac`, `.m4a` | FFmpeg |
77+
| AIFF | `.aiff`, `.aif`, `.aifc` | FFmpeg |
78+
| Apple Lossless[^2] | `.alac`, `.aac` | FFmpeg |
79+
| FLAC | `.flac` | FFmpeg |
80+
| MP3 | `.mp3`, | FFmpeg |
81+
| Ogg | `.ogg` | FFmpeg |
82+
| WAVE | `.wav`, `.wave` | FFmpeg |
83+
| Windows Media Audio | `.wma` | FFmpeg |
84+
85+
### :material-file-chart: Documents
86+
87+
Preview support for office documents or well-known project file formats varies by the format and whether or not embedded thumbnails are available to be read from. OpenDocument-based files are typically supported.
88+
89+
| Filetype | Extensions | Preview Type |
90+
| ----------------------------- | --------------------- | -------------------------------------------------------------------------- |
91+
| Blender | `.blend`, `.blend<#>` | Embedded thumbnail :material-alert-circle:{ title="If available in file" } |
92+
| Keynote (Apple iWork) | `.key` | Embedded thumbnail |
93+
| Krita[^3] | `.kra`, `.krz` | Embedded thumbnail :material-alert-circle:{ title="If available in file" } |
94+
| MuseScore | `.mscz` | Embedded thumbnail :material-alert-circle:{ title="If available in file" } |
95+
| Numbers (Apple iWork) | `.numbers` | Embedded thumbnail |
96+
| OpenDocument Presentation | `.odp`, `.fodp` | Embedded thumbnail |
97+
| OpenDocument Spreadsheet | `.ods`, `.fods` | Embedded thumbnail |
98+
| OpenDocument Text | `.odt`, `.fodt` | Embedded thumbnail |
99+
| Pages (Apple iWork) | `.pages` | Embedded thumbnail |
100+
| PDF | `.pdf` | First page render |
101+
| Photoshop | `.psd` | Flattened image render |
102+
| PowerPoint (Microsoft Office) | `.pptx`, `.ppt` | Embedded thumbnail :material-alert-circle:{ title="If available in file" } |
103+
104+
### 3D Models
105+
106+
<!-- prettier-ignore -->
107+
!!! failure "3D Model Support"
108+
TagStudio does not currently support previews for 3D model files *(outside of Blender project embedded thumbnails)*. This is on our [roadmap](../updates/roadmap.md#uiux) for future features.
109+
110+
### :material-format-font: Fonts
111+
112+
Font thumbnails will use a "Aa" example preview of the font, with a full alphanumeric of the font available in the Preview Panel.
113+
114+
| Filetype | Extensions |
115+
| -------------------- | ----------------- |
116+
| OpenType Font | `.otf`, `.otc` |
117+
| TrueType Font | `.ttf`, `.ttc` |
118+
| Web Open Font Format | `.woff`, `.woff2` |
119+
120+
### :material-text-box: Text
121+
122+
<!-- prettier-ignore -->
123+
!!! info "Plain Text Support"
124+
TagStudio supports the *vast* majority of files considered to be "[plain text](https://en.wikipedia.org/wiki/Plain_text)". If an extension or format is not listed here, odds are it's still supported anyway.
125+
126+
Text files render the first 256 bytes of text information to an image preview for thumbnails and the Preview Panel. Improved thumbnails, full scrollable text, and syntax highlighting are on our [roadmap](../updates/roadmap.md#uiux) for future features.
127+
128+
| Filetype | Extensions | Syntax Highlighting |
129+
| ---------- | --------------------------------------------- | :--------------------------------: |
130+
| CSV | `.csv` | :material-close-circle:{.lg .red} |
131+
| HTML | `.html`, `.htm`, `.xhtml`, `.shtml`, `.dhtml` | :material-close-circle:{.lg .red} |
132+
| JSON | `.json`, `.jsonc`, `.json5` | :material-close-circle:{.lg .red} |
133+
| Markdown | `.md`, `.markdown`, `.mkd`, `.rmd` | :material-close-circle:{.lg .red} |
134+
| Plain Text | `.txt`, `.text` | :material-minus-circle:{.lg .gray} |
135+
| TOML | `.toml` | :material-close-circle:{.lg .red} |
136+
| XML | `.xml`, `.xul` | :material-close-circle:{.lg .red} |
137+
| YAML | `.yaml`, `.yml` | :material-close-circle:{.lg .red} |
138+
139+
### :material-file: Other
140+
141+
| Filetype | Extensions | Preview Type |
142+
| -------- | ---------- | -------------------- |
143+
| EPUB | `.epub` | Embedded ebook cover |
144+
145+
<!-- prettier-ignore-start -->
146+
[^1]:
147+
The `.jpg_large` extension is unofficial and instead the byproduct of how [Google Chrome used to download images from Twitter](https://fileinfo.com/extension/jpg_large). Since this mangled extension is still in circulation, TagStudio supports it.
148+
149+
[^2]:
150+
Apple Lossless traditionally uses `.m4a` and `.caf` containers, but may unofficially use the `.alac` extension. The `.m4a` container is also used for separate compressed audio codecs.
151+
152+
[^3]:
153+
Krita also supports saving projects as OpenRaster `.ora` files. Support for these is listed in the "[Images](#images)" section.
154+
155+
<!-- prettier-ignore-end -->

‎docs/stylesheets/extra.css‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,19 @@ h2,
9797
.priority-low {
9898
color: #28afff;
9999
}
100+
101+
.red {
102+
color: rgb(245, 0, 87);
103+
}
104+
105+
.amber {
106+
color: rgb(255, 145, 0);
107+
}
108+
109+
.green {
110+
color: rgb(0, 191, 165);
111+
}
112+
113+
.gray {
114+
color: rgb(158, 158, 158);
115+
}

‎docs/updates/roadmap.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ Features are given rough estimations for which version they will be completed in
3535
An improved SQLite-based library save file format in which legacy JSON libraries are be migrated to.
3636
Must be finalized or deemed "feature complete" before other core features are developed or finalized.
3737

38+
<!-- prettier-ignore -->
39+
!!! note
40+
See the "[Library](#library)" section for features related to the library database rather than the underlying schema.
41+
3842
- [x] A SQLite-based library save file format **[[v9.5.0](./changelog.md#950-2025-03-03)]**
3943
- [ ] Cached File Properties Table :material-chevron-triple-up:{ .priority-high title="High Priority" } **[v9.6.0]**
4044
- [ ] Date Entry Added to Library :material-chevron-triple-up:{ .priority-high title="High Priority" }
@@ -88,6 +92,10 @@ A detailed written specification for the TagStudio tag and/or library format. In
8892
- [ ] 3D Model Thumbnails/Previews :material-chevron-triple-up:{ .priority-high title="High Priority" }
8993
- [ ] STL File Support
9094
- [ ] OBJ File Support
95+
- [ ] Plaintext Thumbnails/Previews :material-chevron-triple-up:{ .priority-high title="High Priority" }
96+
- [x] Basic Support
97+
- [ ] Full File Preview :material-chevron-triple-up:{ .priority-high title="High Priority" }
98+
- [ ] Syntax Highlighting :material-chevron-double-up:{ .priority-med title="Medium Priority" }
9199
- [ ] Toggleable Persistent Tagging Panel :material-chevron-triple-up:{ .priority-high title="High Priority" }
92100
- [ ] Top Tags
93101
- [ ] Recent Tags

0 commit comments

Comments
 (0)