Edit and update of FAQ+new database GUI guide

[aviv926]

Added edit and update of FAQ:

• Division by subject
• Editing of irrelevant things (object detection) + cloudflare 100M limit
• Adding many repetitive questions to FAQ
• Adding a "comparison" page in the overview for people from different platforms
• Added all kinds of explanations about how ML works

Instructors:
Added database login guide using PgAdmin (GUI).

Note:
My English is not 100% and I use a translation, maybe you should follow grammar and words that probably weren't translated properly, I did my best so that there are no situations where there is a spelling mistake

Note 2:
i want to use docusaurus with
import TOCInline from '@theme/TOCInline';

https://docusaurus.io/docs/markdown-features/toc#inline-table-of-contents

So that I can display all the TOC from all MD pages in FAQ.mdx
For a quick search for a question among all FAQ departments

Do you think there is a way I can make this happen?

It's not finished yet, but I'd like you to take a look at it

[danieldietzler]

You should be able to npm i @theme/TOCInline in the docs/ folder and then the import in the faq.mdx file should work. (You can only use react/ts stuff in *.mdx files)

[danieldietzler]

First off, content-wise it's already really good and very helpful!

Sorry if seeing 38 review comments is a little slaying. It ended up being a lot of little nitpicks but I think that's what you wanted, especially given that you used a translator for it.

I've sometimes skipped sections that felt WIP.
Generally, you should pay attention to capitalization and missing periods (there are just multiple sentences without a '.')
I hope this is somewhat helpful though! :) Really appreciate your hard work on this (so far)!

[aviv926]

First off, content-wise it's already really good and very helpful!

Sorry if seeing 38 review comments is a little slaying. It ended up being a lot of little nitpicks but I think that's what you wanted, especially given that you used a translator for it.

I've sometimes skipped sections that felt WIP.
Generally, you should pay attention to capitalization and missing periods (there are just multiple sentences without a '.')
I hope this is somewhat helpful though! :) Really appreciate your hard work on this (so far)!

Wow, that's great! I will work on the fixes soon! Thanks for the corrections and your time :)

[mertalev]

Thanks for working on this! My feedback is generally about making the FAQ as useful as possible for the average user. When in doubt, keep it simple. Also, don't link to spreadsheets, Discord or Reddit. The information in the FAQ should stand on its own and be presented in an accessible way.

[aviv926]

I will soon make all the necessary corrections.
I thought I would add more questions to the FAQ, I would like to know if it could be relevant in your opinion.
@danieldietzler @mertalev

Under Assets -> How to delete transcoded assets if I don't need them anymore?
(Actually I'm not 100% sure about the answer because I saw in Discord the answer that ZACK answered https://discord.com/channels/979116623879368755/994044917355663450/1186359061265010748 but I couldn't figure out if it's something that exists or not).

Under Assets -> What happens when 2 users have access to load from the same library?
A. All machine learning jobs and thumbnail images are recreated.

Under Assets -> Is it possible to use item compression like in App-Which-Must-Not-Be-Named.?
A. No. There was a discussion about this in the past but it was rejected, there is an unofficial way to achieve this.
https://gist.github.com/JamesCullum/6604e504318dd326a507108f59ca7dcd.
I will add what you mentioned about the security of it

Under performance -> I disabled machine learning but I still experience high CPU usage why?
A.The process of creating the thumbnail images is based on the CPU, so the CPU usage can still be high until the creation of the thumbnails is finished.

Under ML -> Does Immich have animals recognition?
A.No.

Under Mobile application -> I can't log into the application after the server update, what can I do?
A. update the app.

[danieldietzler]

1. That's currently not a thing. You'd need to do it manually by querying the database and comparing it to the local files I guess. So imo not really feasible. Easiest for (not too large) libraries would probably be to just delete the folder and re-generate all files. Since this isn't really a good approach either I'd vote for leaving this point out for now.

2. I'm not sure if it's that helpful but it can't hurt either

3. Sounds good (I guess?)

4. Sounds good

5. Sounds good ("animal", not "animals")

6. Maybe also explain that app store updates sometimes take longer because the stores (play store; google and app store; apple) need to approve the update first which may take some time

[aviv926]

1

Great, I'll start working on everything soon,
If you have any other suggestions I will add them as well.

[mertalev]

Under Assets -> How to delete transcoded assets if I don't need them anymore?

This would be a good addition, but only after we actually implement #5873

Under Assets -> What happens when 2 users have access to load from the same library?

This is good, but reword to "What happens if an asset exists in more than one account?".

Under Assets -> Is it possible to use item compression like in App-Which-Must-Not-Be-Named.?

Eh sure, but just say it isn't supported.

Under performance -> I disabled machine learning but I still experience high CPU usage why?

I think this is redundant if we have a "Why is Immich using so much of my server's CPU?" question that explains which jobs are CPU-intensive.

Under ML -> Does Immich have animals recognition?

This is good.

Under Mobile application -> I can't log into the application after the server update, what can I do?

This is also good.

[danieldietzler]

Nice, some more minor things. Also, it there are a few open issues still from my last review :)

[danieldietzler]

I believe the question you're actually answering is "Which models are being used?"

[mertalev]

This was actually my suggestion. I was thinking we could flesh it out some more and have that be the question. Do you think it'd be better for them to be separate questions?

[danieldietzler]

I basically don't know anything about machine learning stuff and reading the respective text did not explain to me how facial recognition works. I don't think I have a preference on either making it two questions or extending the current text. All I'm saying is that the question right now isn't being answered by the text :)

[aviv926]

Actually I can try to expand on this, but if we're going to expand on it, maybe you should put it in one of these:

https://immich.app/docs/features/facial-recognition/
or here
https://immich.app/docs/administration/jobs
or
https://immich.app/docs/developer/architecture

In any case, I think that an extended explanation would definitely be something welcome, it would allow contributors to the code or people to understand how the models work in Immich. I understand that it may not be of interest to everyone, but people can be directed to read a research article if they are interested in the depth of things

Here is my suggestion:

Immich uses InsightFace to perform
face detection and recognition.
Every time a new property is uploaded to Immich, thumbnails are created for it.
InsightFace uses machine learning to identify faces in thumbnails, for each face a unique identifier is created, also called an embed, and it belongs to the Postgers database under the face_asset column where the embed values of all the faces in the image + the position of the face in the image are saved, this is saved as a vector value, Immich performs a comparison of :

The embed created for the face from thumbnails of the uploaded asset
Compared to the embeds that exist in a database

Before the additional association there are 2 values that Immich is set to check according to:

1. If a value greater than the MIN DETECTION SCORE defined by the user is received, then Immich will not consider it as a face to add

2. If a value equal to or higher than the MAX RECOGNITION DISTANCE defined by the user is received, then Immich will insert the embed found in the database into the embed of an existing person (if any) if there is no existing person, Immich will create a new person.

For each new embed, Immich performs a test of the 100 closest embeds to the new embed, so that there is no unnecessary load on the system for searching among all the embeds in the database.

@mertalev What do you think of this explanation?
I hope the translation was able to keep my explanation clear enough.

[aviv926]

Do you think this could be an essential addition?
under Assets

How and where are assets stored in Immich?

1. User-Specific Folders:

• Each user has a unique string representing them.
  • The main user is "Admin" (but only for \library\library\)
  • Other users have different string identifiers.
• You can find your user ID in Account Account Settings > Account > User ID.

2. Asset Types and Storage Locations:

• Source Assets:
  • Original assets uploaded through the browser interface&mobile&CLI.
  • Stored in \library\library\<userID>.
• Avatar Images:
  • User profile images.
  • Stored in \library\profile\<userID>.
• Thumbs Images:
  • Preview images (blurred, small, large) for each asset and thumbnails for recognized faces.
  • Stored in \library\thumbs\<userID>.
• Encoded Assets:
  • By default, unless otherwise specified re-encoded video assets for wider compatibility .
  • Stored in \library\encoded-video\<userID>.
• Files in Upload Queue (Mobile):
  • Files uploaded through mobile apps.
  • Temporarily located in \library\upload\<userID>.
  • Transferred to \library\library\<userID> upon successful upload.

:::danger
Do not touch the files inside these folders under any circumstances except taking a backup, changing or removing an asset can cause untracked and missing files.
You can think of it as App-Which-Must-Not-Be-Named, the only access to viewing, changing and deleting assets is only through the mobile or browser interface.
:::

How can I hide photos from the timeline?

You can archive them.

What happens if I changed or canceled vdeo transcoding ?

If you chose to cancel the vdeo transcoding, the transcoded videos will be deleted, if you chose to change the encoding format, the newly encoded videos will overwrite the old ones.

---

under Machine Learning

The immich_model-cache volume takes up a lot of space, what could be the problem?

If you installed several models and chose not to use some of them, it might be worth deleting the old models that are in immich_model-cache.
To be able to do this you can run:
docker run -it --rm -v immich_model-cache:/mnt ubuntu bash
cd mnt
ls
and delete unused models with rm -r <model_name>.

[mertalev]

The first question is out of scope for a FAQ, but the others are good. The transcoding answer is wrong though because it won't delete on cancel.

[aviv926]

The first question is out of scope for a FAQ, but the others are good. The transcoding answer is wrong though because it won't delete on cancel.

Thank you for your review!

1. Doesn't your PR feat(server): delete unnecessary encoded videos #6027 deal with the removal of irrelevant encoded videos/after deactivation? The question I wrote came from a conversation in Discord and after I saw the PR you created and merged into the project.

2. About the first question maybe I need to put it under the backup and restore section?
   Here:
   https://immich.app/docs/administration/backup-and-restore#filesystem

3. Regarding all others, I will add 😁

[mertalev]

1. Transcodes are only deleted if they already existed beforehand for a job and the job found transcoding to be unnecessary. Canceling transcoding jobs won't have this effect. Canceling active jobs is not possible, so they will still process as normal. Canceling queued jobs is the same as never queueing them to begin with.

2. That seems like a good place for it.

[aviv926]

1. Transcodes are only deleted if they already existed beforehand for a job and the job found transcoding to be unnecessary. Canceling transcoding jobs won't have this effect. Canceling active jobs is not possible, so they will still process as normal. Canceling queued jobs is the same as never queueing them to begin with.
2. That seems like a good place for it.

That means a user can't decide to delete the conversions if he wants to right now?
And if the user decides to delete it manually, it will create "not tracked" on the repair page

If so, the answer to this question will be that as long as the asset is not deleted through the browser interface, the transcode created will continue to exist. Right?

[mertalev]

1. Transcodes are only deleted if they already existed beforehand for a job and the job found transcoding to be unnecessary. Canceling transcoding jobs won't have this effect. Canceling active jobs is not possible, so they will still process as normal. Canceling queued jobs is the same as never queueing them to begin with.

2. That seems like a good place for it.

That means a user can't decide to delete the conversions if he wants to right now?

And if the user decides to delete it manually, it will create "not tracked" on the repair page

If so, the answer to this question will be that as long as the asset is not deleted through the browser interface, the transcode created will continue to exist. Right?

No, that's not right. A user can delete a given existing transcode if they set a transcode policy that makes it unnecessary and then run a transcoding job for it. This can be done on a per-asset basis by starting a transcoding job for an asset, or for all assets by running transcoding jobs for all assets.

[aviv926]

No, that's not right. A user can delete a given existing transcode if they set a transcode policy that makes it unnecessary and then run a transcoding job for it. This can be done on a per-asset basis by starting a transcoding job for an asset, or for all assets by running transcoding jobs for all assets.

Good to know, I'll add that as answer:

If user choose to transcode policy that makes it unnecessary and then run a transcoding job, it will delete unnecessary transcodes.
This can be done on a per-asset basis by starting a transcoding job for an asset, or for all assets by running transcoding jobs for all assets.

If user choose to changed transcode policy and rerun transcoding job for an asset, the newly encoded videos will overwrite the old ones. 

By the way In your opinion it would be necessary to specify at libraries
that if you want to add a folder that contains spaces in its name, it must have a - instead of a space? Or is this something that Immich can be made to do automatically and will be fixed in future versions? According to Jrasm spaces are problematic in general when it comes to programming, so I'm wondering if it should be noted in the documentation.

[aviv926]

That can be a separate PR, though. This one should just be about updating the FAQ itself.

agree.

In your opinion under Comparison.md it would be necessary to add

::: Tip
If you have chosen to move definitively from Photoprism to Immich, you may want to check how to perform migrating favorites and albums from Photoprism to Immich.
:::

Is it also worth adding information about the feature that Immich has keyboard shortcuts? If so, where?
I mean to -> Shift + ?

[jrasm91]

I think it would be better if all the FAQs where on a single page. We can still group them into sections (on a single page) and make them collapsible, which I think makes the content more accessible rather than having to page through 10 different pages. Also, existing FAQ links would all be broken.

[jrasm91]

If you move everything back into a single page, I'm happy to help look into some react component or format that would make it more usable.

[aviv926]

If you move everything back into a single page, I'm happy to help look into some react component or format that would make it more usable.

I was thinking about putting it all on the same page as it was before I started working on it, like I mentioned in the first message of this PR.
My idea was to use the TOC that support by Docusaurus see example here
The thing is, I won't able to use <TOCInline toc={toc} /> as <TOCInline toc={example.md} />
If it worked, I would try to import all TOCS from other md pages...but it dosn't /:

So my final idea was to do something that was not very smart... but it works.
The idea is to copy all TOCS from the right side and also the link (with JS code) and manually put it on the first page.
Unless you think of a better way.

[jrasm91]

I think it would be better if they were all in the same page.

[danieldietzler]

If we may want to add a TOC for other things I could look into this but I agree with Jason in that the FAQ should be just one page - with maybe an "accordion" component or something, so that single sections can collapse.

[aviv926]

If we may want to add a TOC for other things I could look into this but I agree with Jason in that the FAQ should be just one page - with maybe an "accordion" component or something, so that single sections can collapse.

I managed to create a code that will do the job so that the previous comment is not relevant, now it is generated automatically.

For example:

But if it's not part of what works for Immich I'll change it all to one page.
Let me know what your thoughts are on my suggestion and I will change accordingly.

[jrasm91]

I don't think we only want a table of contents. We want the actual content all together in one place, on the same page.

[aviv926]

I don't think we only want a table of contents. We want the actual content all together in one place, on the same page.

Got it, I'll upload a one page version for everything soon.

Sorry for all the commit alerts...I'm pretty new to this

[aviv926]

@jrasm91 I moved everything to the configuration of AIO
I think it's a bit messy because after the new additions the page contains a lot of information.

[jrasm91]

Thanks for working on this! The additional information is great and we can iterate on this page over time to continue to fine tune and improve it.

I think this actually looks really good on a single page. You can easily search for everything and content is very discoverable (plus, all the old links still work 🎉).

stale

[aviv926]

Thanks for working on this! The additional information is great and we can iterate on this page over time to continue to fine tune and improve it.

I think this actually looks really good on a single page. You can easily search for everything and content is very discoverable (plus, all the old links still work 🎉).

Thanks for the merge :)

Regarding the GUI guide of the database, I saw that you removed the EXTRA part, it is mainly for Ubuntu users, there is no GUI as software, it is a GUI through the browser, so I added information for those who want to find out where the link to connect to the database via PgAdmin is

[jrasm91]

Are you talking about those running a headless server?

[aviv926]

Are you talking about those running a headless server?

I mean those running Immich on a Linux system like Ubuntu, where there is no GUI for the pgAdmin software and you have to use a browser for a user interface. This is explained in the manual in the EXTRA section.

In addition, I added up-to-date information regarding backup in a Windows-based system and information about the new storage format on new and old machines.
Is this required in your opinion?

[jrasm91]

I'm not sure I understand. I use pgAdmin and I'm on ubuntu and it works fine.

[aviv926]

I'm not sure I understand. I use pgAdmin and I'm on ubuntu and it works fine.

Maybe it was just me...
When I tried to develop a new feature in Immich I had to check the database in Ubuntu, it took me too much time than expected because in Windows it was easy, just run the software and connect to the database.
In Ubuntu the interface of the software was through the browser and it took me a while to figure it out
In any case, it's probably not that important, so we'll leave the guide as it is (just need to fix the links to the pgAdmin website, I've created a commit aviv926@3e01667)