Rich Terminal Interfaces with Ratatui

this is Ratatouille a Tui framework in Rust that is replacing the two ERS project as the successor if you don't know what a 2E is this is a Tui this is running in my terminal and it has a bunch of graphs a bunch of data being generated in this case we've got sparklines and gauges and all sorts of other widgets like charts if I go up and down with the up and down arrows you can see the list on the left hand side here is increasing or decreasing depending on whether I'm going down or up and if I go left and right it will change two tabs which you can see at the top here we've got tab 0 tab 1 which is a map setup and tab three or two depending on how you want to index it so if you want to build in-depth experiences in your terminal or you just enjoy spending more time in your terminal emulator Ratatouille is for you now I wanted to see how easy it was to integrate Ratatouille into my own applications and I have a example app here that is trying to do some audio processing using cpal now my end goal with this is that it will go from cpal to wgpu but before before I have the wgpu backend ready I wanted to see if it could render the decibel level of my microphone in the terminal which you are seeing right here this is a sparkline for which zero is the bottom so louder sounds make the bars go smaller because I'm just running dot absolute value on the f32s which are all negative so decibels come in negative 100 is super low volume you probably wouldn't hear it while like negative five is pretty high and they're just reversed on this chart so lower is higher and higher is lower that's why for the most part when I'm talking you can see these huge valleys because I'm actually talking and it's going in and recording whereas when I stop talking which I often don't show in videos you see these higher blocks and Ratatouille has turned out pretty nice so if I create a new terminal here and I sort of drag this up to be kind of okay sit in the top left corner or something I'm showing enough data or trying to show enough data that this will still have data to show along the entire width of the screen and you can see that it's fairly response to the size of my terminal now I'm not sure if this will come through on the video but it is a little choppy on my side so I can stop this and pull on 50 milliseconds instead of 250. and now when I'm pulling every 50 milliseconds you can see all the data throwing by much faster is a little bit less chunky and I've totally arbitrarily chosen the parameters of this kind of demo so I'm just going to put it back to 250 and I'm going to let it be a little chunky because it doesn't really matter to me so two things I noticed from using Ratatouille the first is that the hard part is not really setting up the terminal UI the UI comes down to basically you have to get your data in somehow and then you have to set up the little component in whatever layout you want it to be in so this is a UI component it takes some frame there's some state which I've wrapped in an arc mutex because I'm actually reading this in actively from my microphone that I'm using to record this video live and that's all getting stored in some app state so I'm doing mutex law talking so I can modify the VEC with the decibel value and then when I go to actually render it I take that decibel value by taking the lock again iterating reversing the iterator taking about 300 of the samples well actually not the samples but that's not important absolute valuing them which is why we get a graph that looks like this and then collecting them into a new vac so in this case I've set the layout constraints to A Min of zero but we can also set them to say a length of three so if I include both of these components you can kind of see how that ends up laying out on screen we've got a constraint with a length of 3 which the three refers to the number of lines here you can see if I highlight this there's one line two line and then the third line with the title at the top and then we've got this thing that kind of fills up the rest of the space I'm going to leave it with the constraint with a Min of zero because I kind of like it being the full width of the terminal right now for this video in particular so we've got our sparkline we Define the block with the title in this case we've got borders on the left and the right you can see those white lines so there's some styling options which you can very very easily discover in the docs and of course you can set colors and finally you take the frame you render a widget which is the sparkline with the layout it's supposed to have and that's really it there's a bunch of widgets you put them on the screen you can organize them in different ways you've got tabs you've got graphs you've got other widgets like gauges and there is a little bit of boilerplate to set up and boilerplate to tear down in this case we're using the crossturn back end which we'll cover in a second we get standard in we get standard out we enable raw mode raw mode comes from Cross term execute also comes from Cross terms so you can see that the back end that we're using matters a lot for the setup and the teardown and we create this new terminal with the background the terminal comes from Ratatouille and then once we're done doing whatever we're doing because you know we don't want to run this 2E forever we then have to disable raw mode execute some command for cross term and then show the cursor again so in practice the way this plays out is you kind of have your setup code you have your app running and then you restore the terminal to its previous state so I'm going to leave this decibel visualizer up at the top just because I find a little bit fun for this video now let's dig a little bit into what Ratatouille actually is so first of all Ratatouille is a library for building the rich Tui experiences Tui as opposed to GUI for GUI or graphical user interface this is a fork of the 2E project Tui RS and is as far as I can tell the successor to it at this point it's the most active fork with the most sort of people behind it at the moment adding Ratatouille itself is fairly easy but bear in mind that this is not all you need to do you do also need to add cross term or a different back end so in this case there are three options listed in the readme cross termion and term whiz I will say that cross term being the default makes sense to me specifically because New Shell the shell that I use in all of my videos also uses cross term so in general you're supposed to rebuild the entire UI every time you render it this they mentioned might not be the best for high performance UI visualizations so they do try to minimize sort of the performance impact of that even though in general it tends to not matter so for me for example I'm rendering quite a bit of audio data this is a sample of 44 100 samples per second that is batched into groups of 1024 if I remember correctly that I am then uh taking the max decibel value of for that sampling so I'm getting about 44 we'll say samples per second or 44 decibel levels per second that I need to render out here and that's working just fine you can remember that I could speed this up if I wanted to but I'm actually limiting it myself to 250 milliseconds instead of something that might show more of the data more continuously the Hello World app for Ratatouille is fairly straightforward it is also partially where I got some of the code for setup and teardown I don't write too many two e's so I don't know how often you'd actually want to modify this code but definitely for getting started it feels a little bit like this boilerplate should be encapsulated somewhere there are sort of three relevant areas for the the readme if you're trying to figure out what you can actually show on screen or what already exists out there there's the built-in widgets you can see sparkline right here from what we saw that is the graph right above here is a sparkline and you've also got tabs and tables and other things which are really nice because tables uh as you might not know are usually complicated to implement so it's always nice to have some of those more complicated widgets just readily available the widgets of course come each with their own examples as well as the demo example we saw in the beginning I found from looking at the examples that they're written in an extremely generic way so keep that in mind when you're going through this in this case it supports all three of the back ends because it's the demo but if you go look at say the sparkline demo you'll have to deal with sort of some trait constraints because they do write this to be applicable to any back end even though you might only be using cross term or term whiz or whatever there are of course third-party libraries that already exist many of which were built for the original Tui library that this is a fork of for me one of the most interesting ones here is the sort of text area like widget shown here that allows you to type in a little bit more than maybe other things would you could imagine that this would be really useful if you were building say your own document system or your own note-taking system so you could run your terminal command and pop up whatever you wanted to edit type something really quickly without a full editor bootstrapping and then quit out and then I also highly encourage you to go check out the apps using Ratatouille there are some fun ones like Battleship or even Minesweeper but there are also clients for Spotify or twitch debugging tools and more so this should give you a number of ideas for building your own two applications if you're still a little bit confused as to why somebody would build a Tui so that's all there is for today I actually really enjoyed trying to work with Ratatouille and the problems that I ran into were not related to Ratatouille at all when I was setting up this demo of the sparkline on top the stuff I ran into personally was more that say wgpu uses async apis and cpal doesn't use AP async apis but it stuns its own thread in certain cases but doesn't spawn its own thread in other cases because usually audio is done and a dedicated Hardware or device or whatever it's not super important but I found setting up the actual UI for the text user interface easy or perhaps easier than setting up the data to get actually into the UI itself especially when that data is coming from Real World Systems that all handle data or accessing each of the systems in different ways so I hope you enjoyed this look at Ratatouille I'll see you in the next one have a great rest of your day

Channel: chris biscardi

Views: 31,625

Keywords: rustlang, crossterm, tui

Id: pgFCjtwPBYI

Length: 9min 30sec (570 seconds)

Published: Tue Aug 08 2023