Danh mục API Runtime V2
57 mụcDanh sách đầy đủ các lớp, bộ sưu tập và hàm tự động hóa được tích hợp sẵn trong CogniTab Script Runtime.
📦 Lớp
15 mục- →
AudioClassAudio(name)Giá trị âm thanh chỉ đọc dùng để nhận diện tiếng động trong app hoặc game. Dùng Audio(name) để nạp mẫu đã lưu, hoặc Audio.recent(duration_ms) để lấy đoạn âm thanh vừa thu. Thu và so khớp trên thiết bị; bộ đệm nghe liên tục không được tải lên và script không truy cập âm thanh thô (PCM).
- →
ColorClassColor(value, /)Đại diện cho một màu ARGB và cung cấp helper lấy màu/so sánh màu.
- →
MacroPanelClassMacroPanel(title="", subtitle="", confirm_text="Run", cancel_text="Cancel", *, version="")Tạo và hiển thị panel nhập liệu runtime cho tham số macro trong script.
- →
OverlayTextClassOverlayText(text="", position=(0, 0), color="#FFFFFFFF", size=16, background=None)Vẽ text đè lên màn hình với tùy chọn theo dõi tương tác (ấn/kéo/giữ). Các tên setter như text/background là method; đọc giá trị hiện tại qua state().
- →
PointClassPoint(x, y, /, scale="fixed", anchor="none")Một điểm trên màn hình, đo bằng pixel. Scale/anchor điều khiển cách quy đổi tọa độ giữa các kích thước màn hình. Sau khi quy đổi và cộng offset, runtime sẽ clamp point cuối vào khoảng pixel hợp lệ của màn hình hiện tại. Point có thể bung giá trị thành x, y.
- →
RegionClassRegion(x, y, width, height, /, scale="fixed", anchor="none", scale_param=ScaleParam())Một vùng hình chữ nhật trên màn hình, đo bằng pixel theo trục màn hình hiện tại. Scale/anchor điều khiển cách quy đổi tọa độ theo kích thước toàn màn hình, không xoay qua hệ tọa độ portrait và không dùng app viewport; runtime sẽ clip region cuối vào màn hình hiện tại sau khi quy đổi và cộng offset. ScaleParam điều khiển nhận diện template trong region này. Region có thể bung giá trị thành x, y, width, height.
- →
ScaleParamClassScaleParam(grayscale=True, auto_scale=False, cache_scale=True, template_scale="SHORT_EDGE", fast_matching=False)Các tham số so khớp template cho Region. fast_matching giảm kích thước cả ảnh Region và template.
- →
ScreenCaptureClassScreenCaptureBộ điều khiển tĩnh cho chụp màn hình dùng chung trong lần chạy macro hiện tại. Cache tự động thường dùng lại frame trong tối đa 100 ms để giảm công việc chụp. Khi cần nhận diện liên tục với frame mới nhất hiện có, dùng auto_cache_off(); việc này tăng xử lý và hao pin, không bảo đảm chạy nhanh hơn hoặc có pixel vừa được vẽ mới. cache_on() ghim riêng một frame và được ưu tiên hơn thiết lập cache tự động.
- →
StorageClassStorageKho key/value bền vững dạng static cho macro hiện tại. Biến thường chỉ được dùng chung giữa các action PYTHON_CODE chạy tuần tự trong cùng một luồng chạy, kể cả action bên trong nhóm GROUP; các luồng chạy song song có vùng biến riêng. Key của Storage được dùng chung giữa mọi luồng chạy, vì vậy chỉ dùng Storage khi giá trị cần tồn tại sang lần chạy macro tiếp theo, không dùng như kênh nhắn tin liên tiến trình. Các thay đổi được tự lưu sau 2 giây không có lượt ghi mới và được commit lại sau khi toàn bộ lượt Run cùng mọi luồng chạy nền kết thúc.
- →
SwipePointClassSwipePoint(point, speed="NORMAL", delay_before=0, random=10, humanized=False, scale="fixed", anchor="none")Một điểm trong đường vuốt phẳng. Point phải là Point hoặc tuple (x, y). Truyền list có ít nhất hai SwipePoint vào swipe([...]) để một ngón đi qua nhiều điểm.
- →
SystemClassSystem()Truy cập thông tin hệ thống/thiết bị và gọi hành động hệ thống từ script.
- →
TemplateClassTemplate(name, /)Lớp bọc ảnh template. Bạn có thể scale/crop một template có sẵn, lưu thành tên mới, hoặc kiểm tra tồn tại.
- →
TfliteModelClassTfliteModel(model)Đối tượng model TFLite để dùng trong script. Kiểu model phải được chọn trong metadata của Template Manager. Các đầu ra đang hỗ trợ gồm YOLOv8/YOLO11 object detection [1,N,4+C]/[1,4+C,N], YOLO26 end-to-end detection [1,N,6]/[N,6], YOLO11/YOLO26 image classification [1,C], và MobileNetV3 image classification [1,C]. Runtime tự đọc precision FLOAT32, INT8 hoặc UINT8 từ model và giải lượng tử output detection/classification trước khi áp dụng threshold. Kết quả classification trả confidence và metadata theo class, không dựng point hoặc bounds giả. Các hàm inference yêu cầu file model cục bộ; nếu thiếu file local và runtime tải lại thất bại thì script sẽ báo lỗi runtime.
- →
TimerClassTimer(auto_start=True)Đồng hồ bấm giờ theo millisecond dùng để kiểm tra thời lượng và chờ có điều kiện trong script.
- →
TouchClassTouchHelper tĩnh cho các click/swipe chạy song song được tạo bởi UI hoặc code click(..., parallel=True), swipe(..., parallel=True). Bạn có thể gom các click/swipe lại rồi gửi một lượt, hoặc lấy thông tin về các click/swipe đang nhấn/đang chờ. Helper cũng cung cấp khả năng huỷ click/swipe đang hoạt động (chỉ hoạt động đối với Android 8.0+).
🔒 Lớp chỉ đọc
6 mục- →
AudioMatchRead-only ClassAudioMatchKết quả so khớp âm thanh chỉ đọc. Điểm là mức tương đồng, không phải xác suất chính xác. Mốc thời gian của find() tính từ đầu phiên nghe; match() dùng mốc thời gian của giá trị âm thanh được tìm kiếm. So sánh mốc thời gian để tránh xử lý lặp cùng một âm thanh. Chỉ dùng mốc thời gian làm lần phát hiện khi matched là True.
- →
FlowRead-only ClassFlowBộ điều khiển static để khởi chạy song song các luồng chạy có tên của macro. Tối đa hai luồng chạy nền có thể chạy cùng luồng chạy chính và mỗi tên chỉ được có một lượt gọi còn sống, kể cả khi đang tạm dừng hoặc đang dừng. Flow.start() trả về ngay sau khi bộ điều phối chấp nhận nhánh; luồng chạy nền có thể khởi chạy luồng ngang hàng. Biến được tách riêng theo từng nhánh và không bao giờ hợp nhất về nhánh gọi. Luồng chạy chính chờ mọi luồng chạy nền trước khi lượt Run hoàn tất. Tên không hợp lệ hoặc trùng, hết chỗ chạy nền, lỗi ở bất kỳ nhánh nào, System.stop() hoặc nút Stop của Main đều kết thúc toàn bộ macro. Mỗi điều khiển dock có số của luồng chạy nền chỉ có thể tạm Pause hoặc Resume riêng nhánh đó; không có Stop riêng từng nhánh. Pause hoặc Resume của Main áp dụng cho mọi nhánh, và Resume toàn cục cũng xóa cờ pause cục bộ của nhánh. Cử chỉ chạm từ các nhánh khác nhau có thể hủy lẫn nhau. Chính sách ScreenCapture và audio capture được dùng chung toàn cục. Storage dùng chung các key bền vững giữa các nhánh và không phải kênh nhắn tin liên tiến trình.
- →
MatchRead-only ClassMatchKết quả nhận diện dạng chỉ đọc, được trả về từ các hàm region.find*. Trong nhánh Thành công của nhận diện, Recognition.result trỏ tới Match hoặc MatchList nhận diện hiện tại.
- →
MatchListRead-only ClassMatchListMột list chỉ đọc gồm các giá trị Match, được trả về từ region.find_any/find_all/find_multi, wait_any/wait_all và Recognition.result khi nhiều mục tiêu nhận diện cùng khớp.
- →
RecognitionRead-only ClassRecognitionĐược dùng trong nhánh thành công của nhận diện trong UI. Recognition.result trả về Match khi có một mục tiêu nhận diện khớp hoặc MatchList khi nhiều mục tiêu cùng khớp.
- →
TouchStateRead-only ClassTouchState(id, status, kind, action_order, remaining_repeats, completed_repeats)Ảnh chụp trạng thái của một touch script/UI trong hàng đợi gesture dùng chung.
📚 Bộ sưu tập
5 mục- →
dictCollectiondict(mapping_or_pairs=(), /, **items)Tập hợp key/value giữ thứ tự thêm vào và có thể đọc hoặc cập nhật khi kịch bản đang chạy.
- →
listCollectionlist(iterable=(), /)Danh sách có thứ tự. Dùng khi bạn cần các giá trị có thể đếm, đọc theo vị trí, bung giá trị, hoặc lặp qua theo đúng thứ tự.
- →
setCollectionset(iterable=None, /)Collection có thể cập nhật và chỉ giữ các giá trị không trùng nhau. CogniTab giữ thứ tự lặp ổn định để output script dễ đọc.
- →
StringCollectionStringCollection kiểu văn bản. Tạo bằng string literal hoặc str(value), rồi đọc bằng len/index/vòng lặp.
- →
tupleCollectiontuple(iterable=(), /) (value1, value2, ...)Collection có thứ tự và chỉ đọc. Dùng tuple literal khi dữ liệu không cần thay đổi sau khi tạo hoặc khi gom giá trị để bung vào nhiều biến.
⚡ Hàm
31 mụcThao tác
2 mục- →
clickFunctionclick(target, hold_ms=0, offset=(0, 0), random=0, delay_before=0, delay_after=0, parallel=False)Nhấn vào Point, tuple (x, y), Match hoặc MatchList. Mọi tham số đều hỗ trợ truyền theo vị trí hoặc theo tên theo đúng thứ tự trong chữ ký. Dùng Point(x, y) khi cần thông tin scale/anchor; dùng (x, y) cho tọa độ pixel cố định. Dùng parallel=True để đưa touch vào hàng đợi và nhận id dạng số; gọi Touch.cancel(id) hoặc Touch.cancel() để hủy touch đang queue/active.
- →
swipeFunctionswipe(points, *, parallel=False)Thực hiện thao tác vuốt từ một list SwipePoint phẳng. Mỗi list tạo một đường vuốt nhiều điểm cho một ngón.
Luồng điều khiển
5 mục- →
printFunctionprint(*values, sep=" ", end="\n")In giá trị ra console script của overlay mà không chặn tiến trình chạy. Giá trị có cấu trúc dùng cùng formatter hữu hạn với str(value), gồm pretty output theo từng row cho list hai chiều, output nhiều dòng khi dữ liệu lồng nhau phức tạp và marker rõ ràng khi nội dung bị lược.
- →
randomFunctionrandom()Trả về một số thực ngẫu nhiên trong khoảng 0 -> 1.
- →
random_intFunctionrandom_int(min, max, /)Trả về số nguyên ngẫu nhiên trong khoảng bao gồm cả hai đầu min -> max.
- →
rangeFunctionrange(stop, /) | range(start, stop, step=1, /)Tạo dãy số nguyên để sử dụng trong vòng lặp for.
- →
waitFunctionwait(ms, /)Tạm dừng thực thi script trong một khoảng thời gian (milliseconds).
Bộ sưu tập
4 mục- →
enumerateFunctionenumerate(iterable, start=0)Trả về list gồm các tuple(index, item) cho mọi giá trị có thể lặp.
- →
lenFunctionlen(value, /)Lấy độ dài của String, list/tuple hoặc dict.
- →
sortedFunctionsorted(iterable, /, *, key=None, reverse=False)Trả về list mới chứa mọi phần tử từ iterable theo thứ tự đã sắp xếp. key có thể tính khóa so sánh; reverse=True sắp xếp giảm dần và vẫn giữ ổn định các phần tử có khóa bằng nhau.
- →
zipFunctionzip(*iterables)Ghép nhiều iterable thành list các tuple và dừng ở input ngắn nhất.
Chuyển đổi kiểu
5 mục- →
boolFunctionbool(value, /)Chuyển giá trị thành boolean theo quy tắc truthy/falsy của script.
- →
floatFunctionfloat(value, /)Ép kiểu giá trị về số thực dấu chấm động.
- →
intFunctionint(value, /)Ép kiểu giá trị về số nguyên (cắt phần thập phân).
- →
strFunctionstr(value, /)Chuyển giá trị thành chuỗi theo format hiển thị DSL. Point/Region giữ dạng gọn, list hai chiều hiển thị mỗi row list trên một dòng, và chỉ row quá dài hoặc phức tạp mới tự bung thành nhiều dòng dọc. Giá trị có cấu trúc quá lớn hoặc lồng quá sâu dùng preview hữu hạn với marker báo phần bị lược/ngân sách đã hết; giá trị chuỗi truyền trực tiếp vẫn được giữ nguyên.
- →
typeFunctiontype(value, /)Trả về chuỗi mô tả kiểu theo phong cách Python cho một giá trị, ví dụ <class 'int'>.
Toán học
14 mục- →
absFunctionabs(value, /)Trả về giá trị tuyệt đối.
- →
ceilFunctionceil(value, /)Trả về số nguyên nhỏ nhất không nhỏ hơn value.
- →
clampFunctionclamp(value, min, max, /)Giới hạn value trong khoảng min -> max.
- →
cosFunctioncos(value, /)Trả về cos của value (đơn vị radian).
- →
floorFunctionfloor(value, /)Trả về số nguyên lớn nhất không vượt quá value.
- →
logFunctionlog(value, base=None, /)Trả về logarit của value. Nếu không truyền base thì dùng log tự nhiên.
- →
maxFunctionmax(iterable, /, *, key=None) | max(iterable, /, *, default, key=None) | max(arg1, arg2, /, *args, key=None)Trả về phần tử lớn nhất từ một iterable hoặc giá trị lớn nhất trong hai hay nhiều đối số. key có thể tính giá trị dùng để sắp thứ tự; nếu hòa thì giữ phần tử gặp đầu tiên.
- →
minFunctionmin(iterable, /, *, key=None) | min(iterable, /, *, default, key=None) | min(arg1, arg2, /, *args, key=None)Trả về phần tử nhỏ nhất từ một iterable hoặc giá trị nhỏ nhất trong hai hay nhiều đối số. key có thể tính giá trị dùng để sắp thứ tự; nếu hòa thì giữ phần tử gặp đầu tiên.
- →
powFunctionpow(base, exponent, /)Lũy thừa base với số mũ exponent.
- →
roundFunctionround(value, digits=0, /)Làm tròn giá trị theo số chữ số thập phân chỉ định.
- →
sinFunctionsin(value, /)Trả về sin của value (đơn vị radian).
- →
sqrtFunctionsqrt(value, /)Trả về căn bậc hai của giá trị không âm.
- →
sumFunctionsum(iterable, /, start=0)Trả về tổng số học của một iterable, có thể bắt đầu từ giá trị start. Generator expression chỉ được bỏ cặp ngoặc riêng khi là đối số duy nhất của lời gọi hàm hoặc phương thức; nếu có đối số khác hoặc dấu phẩy cuối thì phải bọc generator trong ngoặc.
- →
tanFunctiontan(value, /)Trả về tan của value (đơn vị radian).