ctdoshot

Menu-bar screenshot tool for macOS: capture, annotate, copy/save.

By ctdoteam · GitHub

Documentation (localized)

Language	File
English	docs/README.en.md
Tiếng Việt	docs/README.vi.md
简体中文	docs/README.zh-CN.md
日本語	docs/README.ja.md

---

Highlights

Area	What you get
Capture	Region, fullscreen, active window, last region, scrolling stitch
Editor	Arrow, text, steps, rect, freehand, crop, pixelate blur, undo/redo
Export	Clipboard (⌃C / ⌘C), save PNG/JPEG, file path on pasteboard, pin-to-screen
OCR	Vision text recognition (EN / VI / JP), history search by OCR
Workflow	After-capture Show / Copy / Save, Esc actions, recordable global hotkeys
i18n	English + Tiếng Việt UI strings

Bundle ID: com.ctdoshot.app · Menu-bar app (LSUIElement)

---

Screenshots

Add product shots under docs/images/ when available.

Capture overlay	Editor	Preferences
Coming soon	Coming soon	Coming soon

---

Requirements

• macOS 13 or later
• Screen Recording permission (System Settings → Privacy & Security)
• Xcode 15+ (or full Xcode app) to build and run tests
• Swift 5.9+

swift build may work with Command Line Tools alone. swift test requires full Xcode (xcode-select must point at an Xcode.app).

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

---

Install (from source)

git clone https://github.com/TIPC1110/ctdoshot.git
cd ctdoshot

# Once per machine: stable code-signing cert (keeps Screen Recording across rebuilds)
./scripts/ensure-signing-identity.sh

# Release .app
./scripts/package-app.sh
open build/ctdoshot.app

# Optional: install to /Applications so the path never changes
# CTDOSHOT_INSTALL=1 ./scripts/package-app.sh && open -a ctdoshot

First launch — Screen Recording

1. Open System Settings → Privacy & Security → Screen Recording
2. Enable ctdoshot
3. Quit fully (⌘Q) and open the same .app again

Always use the packaged .app (or /Applications/ctdoshot.app).
swift run / raw .build/ binaries are different identities and re-prompt.

Why rebuild used to re-ask: ad-hoc signing (codesign -s -) changes the binary hash every build, so macOS treats each package as a new app.
ensure-signing-identity.sh creates a named cert (ctdoshot Developer); package-app.sh signs with it so TCC can stick.

If permission is still sticky after switching from ad-hoc → cert:

tccutil reset ScreenCapture com.ctdoshot.app
./scripts/package-app.sh
open build/ctdoshot.app
# grant once, quit, reopen

---

Usage

ctdoshot lives in the menu bar (camera / viewfinder icon).

Capture

Action	Default hotkey
Capture area	⇧⌘S
Capture screen	⇧⌘3
Capture active window	⇧⌘W
Capture last region	⇧⌘L
Scrolling capture	⌥⇧⌘X
OCR quick (region → clipboard text)	⌃⌥⌘O
History	⇧⌘H

Hotkeys are rebindable in Preferences → Hotkeys (click a row, press a new chord).

Editor

After capture (when “Show” is enabled):

• Draw: arrow, rectangle, pencil, step numbers, text
• Crop and blur / mosaic (pixelate)
• ⌃C / ⌘C — copy annotated image (editor stays open)
• ⌘S / Save & Copy — save file (+ path on clipboard when copy is on)
• ⌘Z / ⇧⌘Z — undo / redo
• Esc — optional copy/save then close (Preferences → Advanced)

Preferences

• Language (System / English / Tiếng Việt)
• Save folder, format (PNG / Auto JPEG), downscale Retina
• After screenshot: Show / Copy / Save
• OCR language, strip line breaks
• Launch at login
• Global hotkey recorder

---

Development

Project layout

Sources/
  ctdoshotApp/          # @main entry
  ctdoshotCore/         # App logic (capture, editor, OCR, hotkeys, UI)
Tests/ctdoshotTests/    # XCTest
packaging/              # Info.plist, entitlements
scripts/package-app.sh  # release .app + ad-hoc codesign

Build

swift build                 # debug
swift build -c release      # release binary → .build/release/ctdoshot
./scripts/package-app.sh    # → build/ctdoshot.app (native architecture)

# Build Universal Binary (arm64 + x86_64) without Xcode GUI:
./scripts/package-app.sh --universal

# Cross-compile for Mac Intel (x86_64) directly from Apple Silicon Terminal:
./scripts/package-app.sh --intel

Test

swift test
# or explicitly:
DEVELOPER_DIR="$(xcode-select -p)" swift test

Architecture (short)

• Capture: ScreenCaptureKit (in-process; no screencapture CLI) + region overlay
• Annotation: vector tools, image-space coordinates, CG bake on export
• OCR: Vision VNRecognizeTextRequest
• Hotkeys: Carbon RegisterEventHotKey + HotkeyStore persistence

---

Roadmap

Planned / partial (see design docs):

• Richer scrolling stitch reliability
• Window capture background styles (wallpaper / shadow trim)
• Video / GIF recording
• Upload destinations (optional plugins)
• Notarized release builds

Contributions welcome — open an issue first for large features.

---

Contributing

1. Fork the repo and create a branch (feature/… or fix/…)
2. Keep changes focused; run swift test before pushing
3. Prefer packaged-app testing for anything involving Screen Recording
4. Open a Pull Request against main with a clear description

Bug reports: include macOS version, how you launched the app (.app vs swift run), and whether Screen Recording is enabled for ctdoshot.

---

Privacy

ctdoshot runs locally. Screenshots and OCR stay on your Mac unless you copy, save, or share them yourself. Screen Recording is used only to capture displays/windows you request.

---

Acknowledgments

• Built for everyday capture workflows on macOS

---

License

MIT © ctdoteam

Copyright (c) ctdoteam

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Links

• Repository: https://github.com/TIPC1110/ctdoshot
• Issues: https://github.com/TIPC1110/ctdoshot/issues
• Team: ctdoteam

---

_{ctdoshot by ctdoteam
Hoang Sa and Truong Sa are Vietnamese territories.}